// comment

To use this library you will need the latest version of BV Terminal. There are only two files and it does not need to be installed. Go to the download page for the latest Forth related files ** including Free Forth **

Given the combination of this library, a suitable platform for running BV Forth and the BV Terminal Version 3, this has the makings of a powerful development system. This is best illustrated by a simple example.

The example is to use a BV511 and flash the built in LED on and off, this is described in the BV Foundation book that comes with the BV511 but the software has been updated since then so this example takes a different approach. Looking at the first word to set up the LED:

// #URL-lib "http://pin1.org/forthlib/flb/general/pinsel.flb"

variable tog
// set p31 to an output, -ve numbers are used for port 1 and

// +ve for port 0

: p0.31-setup

31 io-out // set p0.31 to o/p
0 tog ! // set variable to 0
;

If the above word 'p0.31-setup' uses io-out and so compiling this word on its own in a clean system would fail, this is because io-out is defined elsewhere. It is in fact defined in pinsel.flb. By including this:

As a comment and using BV Terminal 3 (BVT) the word will compile correctly. This is because BVT will load the pinsel.flb into its memory and search for io-out which it will find and compile the definition of this into the code, note that is is loaded from the internet, so providing you have an internet connection the file will always be there, in this location, even if you move to a different computer. (educational institutions take note). A big advantage of course is BVT along with BV Forth is clever enough to only load those words that are required. The rest of the code for p0.31 can be found in the examples section, selected by the menu on the left. To look into this further see this page.

Some Notes

This section of pin1.org is a php driven interface for browsing Forth files and libraries of files. when you select a file, to use it as a library you can cut and paste the details given at the top, you can also download the file to a local directory if you wish. If you are using a local library file then the directive id // #Library, rather than // #URL-Lib. For more information on BVT directives see the BVT manual.

This is also a great opportunity to use SID, for an explanation of this see this page.

Page Layout for this Site

Although BVT and BV Forth don't care about the layout of the code, to make the code look nice for this site here are some rules:

In general a section or piece of code should be followed by a blank line. At the beginning of the file there should be a description using this // type of comment, the end of the description is a blank line. You can incorporate a REQUIRES: section by using that very word and a CONSTANTS: section, Both of those keywords are used to find the sections and they terminate with a blank line. A colon or defining word should start at the very beginning of the line followed by 1 space, any comments should be placed above the word using the // comment format. Again it should be terminated with a blank line, this will help the code navigator to jump to the correct place in the file.

Common Problems & FAQ

Note some of the files have the extension flb instead of fth. BV Terminal is not set by default to load those files so change the setup as shown.

When using an on line library that does not exist because of a spelling error or it may simply not exist, there is no obvious sign that something is wrong. Check the lower status window of BVT:

Loading library http://pin1.org/forthlib/flb/generall/soft1.flb      Indexing Library     Index Lines 0
Loading library http://pin1.org/forthlib/flb/generall/pinsel.flb     Indexing Library     Index Lines 0
Loading library http://pin1.org/forthlib/flb/i2c/i2c.flb     Indexing Library     Index Lines 36

In the above example 3 libraries were supposed to have loaded but only two have because of the spelling mistake of 'generall'. The clue is that no lines have been indexed on the two incorrect files.

A limitation of the current (V1.205) Forth is that the text input buffer is set to 80 characters, anything above this will cause an error so if there is a long URL this may exceed 80 characters. The 80 characters includes the whole of the line including the // #.

Nothing in the actual files themselves, they are both text files. However as a general principal an flb file should be compiled with a SID not equal to 0 and it will normally contain private words with a few public (prefixed with <0>) words for inclusion into other files. Files ending with fth are normally source files. A good example of this is the BV4205.flb and the BV4205.fth. The flb file contains lots of words to drive the device and the fth file makes use of those words to give an application example.

It should be noted that all words intended for 'other' use should be public (<0>) if not problems will occur because BVT cannot distinguish between public and private. As an example I2C.flb uses PCLK that is in soft1.fth. If for example soft1.fth had a SID of 100 then when I2C called for the compilation of PCLK, it would get compiled at SID 100, when I2C then tried to look for PCLK it would not find it. The practical outcome is that BVT goes into an endless loop, if you see this happening it is because a library file is looking for a word that has been compiled with its own private SID and thus it will never find it.

To prevent this happening all of the words in soft one have been prefixed with <0>, so if it is used as a library with a SID set to some other value than 0, there will be no consequences.

The BVT will use a cache just a browser does and so any files that change within a session will not be reflected in what BVT downloads as a library. This will almost certainly not be a problem when using the pin1 site but you may encounter it if you are storing and changing your own file son your own site. I believe that closing and restarting BVT clears the cache.

This is where a word is found in the library, used and then can't be found again so this causes BVT to go into an endless loop of getting the word from the library. This is a common problem and is caused by a word from one SID using a word from another without the <0> prefix.

If you want to use a word that is in a library with a different SID then that word must have the SID override prefix <0>, BVT will then compile this word with SID 0 and it will be found by all files because that how SID 0 works. As a general rule a library will only expose (<0>) a small number of words, those words that will be needed by other programs. If however you find that you need lots of words in a particular library, then you are really EXTENDING the library rather then using it. In that case make your program have the same SID as the library.

One method you can use is to extend the library for some of the way and then change the SID later on in the program, as an example:

The above gives the scenario where the code extends the library with SID or 190.

Forth Code Browser

Some Notes

Page Layout for this Site

Common Problems & FAQ