Key Words
Not all keywords are available to all devices, the file system keywords for example will not be available to devices without an SD Card and the screen keywords will not be available to device that don't have a screen.
Cross reference by category:
Reference in Alphabetical Order
% (modulus)
Description:
Returns the modulus of two values
Example:
x = 12 % 4
The modulus returns the remainder of a division and so this will return 0 because 4 divides evenly into 12
&& (logical and)
Description:
Logical and used for making decisions and generally found within a loop or branch structure. This compares two values and evaluates to either true or false.
Example:
if (value1 && value2) = 0 then
code....
endif
& (bitwise and)
Description:
This operator is used for masking bits within a value
Example:
x = y & 0xff
In the above x will contain only the lower byte (8 bits) of y
* (times)
Description:
Multiplies two numbers together
Example:
x = 3 * 3
In the above x will contain the value 6
/ (divide)
Description:
Divides one number by the other
Example:
x = 30 / 3
In the above x will contain the value 10
^ (bitwise exclusive or)
Description:
This is a masking operator that will return the exclusive or of two values
Example:
x = 0x55 ^ 0xf
In the above x will contain the value 0x5a
|| (logical or)
Description:
Logical or used for making decisions and generally found within a loop or branch structure. This compares two values and evaluates to either true or false.
Example:
if (value1 || value2) = 0 then
code....
endif
| (bitwise or)
Description:
This is a masking operation that will return the 'or' of two values
Example:
x = 0xf0 | 0xf
In the above x will contain the value 0xff
~ (complement)
Description:
This will invert all of the bits in a value, if a bit was 1 then it will be 0 and if 0 it will be 1. This is most useful for masking operations where it saves having to define an 'or' and an 'and' mask
Example:
constant RA0 1
@PORTA = @PORTA | RA0 // this will set only the RA0 value high
@PORTA = @PORTA & ~ RA0 // this will set only the RA0 value low
+ (plus)
Description:
Adds two values
Example:
x = 5 + 4
In the above x will contain the value 9
<< (shift left)
Description:
Shift left. The number on the left hand side of << is shifted left by the value on the right hand side. Useful for setting a constant to a bit value for use in registers. If for example RB6 is to be defined then instead of working it out use:
constant RB6 1 << 6
This can now be used in setting registers for example @TRISBCLR = RB6 will set port b line 6 to be an output.
Example:
x = 1 << 4
In the above example 1 is shifted left by 4 positions, this will make the value of x in binary 1000 or 16.
< (less than)
Description:
returns true if the value on the left hand side is less than the value on the right hand side
Example:
if a < b
print "\na is less than b"
endif
<= (less than or equal)
Description:
returns true if the value on the left hand side is less than or equal to the value on the right hand side
Example:
if a <= b
print "\na is less than or equal to b"
endif
<> (does not equal)
Description:
returns true if the value on the left hand side does not equal the value on the right hand side
Example:
if a <> b
print "\na does not equal b"
endif
- (minus)
Description:
Subtracts two values
Example:
x = 5 - 4
In the above x will contain the value 1
= (equal)
Description:
1) Returns true if the value on the left hand side equals the value on the right hand side
2) Is also used as an assignment to set variables
1)
if a = b
print "\na equals b"
endif
2)
x = 77
> (greater than)
Description:
Returns true if the value on the left hand side is greater than the value on the right hand side
Example:
if a > b
print "\na is greater than b"
endif
>= (greater than or equal)
Description:
Returns true if the value on the left hand side is greater than or equal to the value on the right hand side
Example:
if a >= b
print "\na is greater than or equal to b"
endif
>> (shift right)
Description:
The number on the left hand side of >> is shifted right by the value on the right hand side
Example:
x = 0x3200 >> 8
In the above example the second byte in 0x3200 is shifted to the first byte position so the value in x is now 0x32
abs
Description:
Returns the absolute value of an expression
Example:
x = abs(-11)
x will now have the value 11
acos (Floating point)
Description:
returns the arc cosine of a value in radians
Example:
x# = acos(0)
x# will now have the value 1.570, this is 90 degrees in radians
asc
Description:
x=asc(s$,position)
Returns as an integer the value of the character in the string pointed to by position. Zero is returned if position > strlen(s$), the start of the string is 0.
Example:
a$=”hello”
print asc(a$,0) // returns 104 which is the ASCII value for 'h'
print asc(a$,5) // returns 0 because it is beyond the last character position
asin (Floating point)
Description:
returns the arc sine of a value in radians
Example:
x# = asin(1)
x# will now have the value 1.570 which is 90 degrees
atan (Floating point)
Description:
Returns the arc tangent of a value in radians
Example:
x# = atan(1.570)
x# will now have the value close to 1 a 1.570 is approximately 90 degrees in radians
base
Description:
base(<number)
Sets the base of the numbering system, by default this is 10 (decimal) but can also be set to 16 for hex, this really only effect input and output.
Example:
dim j
j=27
base(16)
print j //returns 1B
break
Description:
This is used to break out of a for or while loop before it would normally end. Its is also used with the select case construct
Example:
while value1 < 77
code....
if value1 = 25 then
break
endif
wend
endf
See also for, while, select/endselect
byte2str
Description:
s$=byte2str(x)
Converts a number to a string, this will accept any number and so this is useful for byte buffers.
Example:
print byte2str(65) // returns A
See also chr$ which does a similar job but only returns values inside the printable range
call (introduced version 2.07-77)
Description:
value=call(<code address><pointer to memory>)
This is the mechanism used for calling a machine code function. Provided it uses the GCC stack use calling convention it can be written in C or assembler. The purpose is to provide maximum flexibility giving the best of both the interpretive and compiled worlds. The function will return a 32 bit integer value and will expect a memory address. The handling of the value passed is between the host and the machine code routine, in C this will be cast as a character pointer.
The machine code function when written is placed in flash by the use of a constant and then flsave(""). A machine code function can only be run from flash. Further details can be found here
Example:
Normally an array is filled with the parameters required for the call
v=call(?machine_code(0),?data_to_pass(0))
cart (Floating point) Not available from version 2.3
Description:
d!=cart(8,7,22,23)
Packs a Cartesian co-ordinate into a double word. Each co-ordinate is allocated 16 bits and so can represent an a number from 0 to 65535. This is used for passing co-ordinates to graphic functions but can also be used for any purpose.
Example:
dim d!
d!=cart(8,7,22,23)
x1(d!) contains 7 and y0(d!) contains 22
See also x0,x1,y0,y1
case (select/default/endselect)
Description:
Part of the select/endselect construct See select
cat (File System)
Description:
List the contents of a file as text, used at the command line
Example:
cat fred.txt
cd (File System)
Description:
Changes the current directory, used at the command line
Example:
cd /
chr$
Description:
s$=chr$(x)
Converts a number to a character based on the ASCII table. This is not to be confused with converting a number into a string. The number represented by 'x' above will have a range from 32 to 126, numbers outside this range will return '.'
Example:
print chr$(65) // returns A
See also byte2str which does a similar job but will also return values outside the printable range
cold
Description:
Clears the RAM and all variables. This is effectively a reset, without using reset.
Example:
cold
comclose
Description:
comclose(<port number>)
This command does two things; 1) it switches off the port pins so that those pins can be used for something else and 2) it frees up the buffer that was used.
Example:
comclose(1)
comcts
Description:
comcts(port,REGISTER,BIT)
CTS is an input and when high output transmission will stop. The host will control this line and the com port will monitor it. Port is the same port as used in comopen
REGISTER is the address of the register that is connected to the CTS line and bit defined the line. Note that the BIT is the bit number and not the mask.
Port is a number as used in the UART for comopen. REGISTER is an address of a microcontroller register that will be associated with the port in question and bit is the port line to use.
NOTE:
1) comopen must be used first as this will clear the RTS and CTS
2) the port must be set to input and digital mode.
In this example the PIC32 Port C bit 15 is used for CTS, the addresses have been obtained from the PIC32 family data sheet.
constant TRISCSET 0xbf886088
constant PORTC 0xbf886090
constant LATC 0xbf8860a0
poke(TRISCSET,1 << 15) // sets bit 15 of port C to be input
comcts(1,PORTC,15) //PORTC bit 0 will be monitored
comfill (will not be available in later systems)
Description:
comfill(port,value,#items)
Outputs byte value to the specified port a number of times.
Example:
comfill(2,55,10) // outputs to com 2 “”
comkey
Description:
comkey(<UART>)
This will get the next character in the COM buffer, if there is one. It will wait until there is a character before returning so in certain circumstances it may be wise to use comkey? first to check that there is a character in the buffer. When there is a character in the buffer, this function will remove it from the buffer.
Example:
x = comkey(1) // gets byte from UART 1 or waits until there is one
comkey?
Description:
x=comkey?(port)
Returns the number of characters in the input buffer for that port. An error will be generated if the port is not open
Example:
while comkey?(2) = 0
code.....
wend
The above will execute 'code...' until a key is presses on the host
comopen
Description:
comopen(UART,Baud,Buffer_size)
Opens the COM or UART for reading and writing. UART is a number that refers to the UART on the system – see the data sheet for the particular microcontroller to find out which one to use but it will normally start at 1.
For all BV devices COM2 is the one that is used for the main communication, normally via USB and COM1 is the 'spare' one that the user is free to use. The Baud rate can be any number within the limits of the hardware. The buffer size is the input buffer and is normally set to 80 or 128, this can be increased or decreased depending on the application.
The buffer is dynamically allocated and a warning will be given if there is insufficient memory to allocate the requested size. Closing the port will free up the resource.
Ports can be re-opened with this command in order to change the Baud rate or buffer size or both.
Example:
comopen(1,9600,80)
comout
Description:
comout(port,value)
Outputs a byte value to the specified port
Example:
comout(2,88) // will print 'X' at the console.
comout(2,'X') // will print 'X' at the console.
comouts
Description:
x=comouts(port,s$)
Outputs a string to the designated port and returns the actual number of bytes that were output.
Example:
comouts(2,"fred") outputs "fred" to theconsol
compeek
Description:
value=compeek(port)
This will return the next character in the buffer without removing it from the buffer as comkey would so it enables decisions to be made on the contents of the buffer without having to put a key back if not needed. There must be a key in the buffer to get a meaningful result so comkey? should always be used first.
compeekp
Description:
value=compeekp(port,position)
This is similar to compeek in that it will 'look' into the UART input buffer but with this function there is the ability to look at a particular position along the buffer. The UART buffer is circular and so the actual position varies, the position will be an offset from the start of the get pointer.
To explain further. The get pointer always points to the next charter to be obtained, normally via comkey() and position is added to this so position 0 will obtain the same character in the buffer as comkey() would and position+comkey?() will obtain the character just put in the UART buffer. There is no check that the charters are valid, this is up to the programmer.
comread
Description:
x=comread(port,s$,size,echo)
Reads the specified com port into the supplied string for a maximum of the size given or the size of the string whichever is smaller. The function will return when either \r \n or \0 is received. The actual number of bytes read is returned in x. Setting echo to 1 will also output bytes received.
comrts
Description:
comrts(port,REGISTER,BIT)
This will associate a general purpose port with the RTS (request to send) flow control if it is required. RTS is an output that will stop the host transmitting by setting the line high when the input buffer becomes nearly full. Port is a number as used in the UART for comopen. REGISTER is an address of a microcontroller register that will be associated with the port in question and bit is the port line to use.
NOTE:
1) comopen must be used first as this will clear the RTS and CTS
2) the port must be set to output and digital mode.
Example:
In this example the PIC32 Port C bit 1 (RC1) is used for RTS, the addresses have been obtained from the PIC32 family data sheet.
constant TRISCCLR 0xbf886084
constant LATC 0xbf8860a0
poke(TRISCCLR,2) // set bit 1 to be an o/p
comrts(2,LATC,1) // LATC can be used to directly address the op port
constant
Description:
This is used for associating a value with a symbol and is usually defined at the start of the code so that it can be easily seen and changed if required. It can occur anywhere in the code but not within a function. The symbol name of the function must represent the data type. An expression can form the value and this is efficient as this will only be evaluated once. By convention constant values are usually in upper case.
A constant is stored in the program space rather then the variable space, this means that, if the program is saved to flash its value cannot be changed, hence the name. A big advantage of using a constant is that its value is evaluated at compile time to a single value, so if a constant was defined as some formulae e.g. constant a# (sin(.8) * 6)/2. Then this would be only evaluated once, thus saving space and increasing execution speed.
Version 2.06 onwards.
** Special Note: BV_COM 1.34 and BVserial is designed to work with the 'flash' and {} keywords, downloading these constructs will require this version or above.
From this version there is a new method of specifying values for a constant using curly brackets, this only applies to string ($) and integer types. In addition to accommodate long tables the '\' can be used to carry on to the next line. The string type will hold byte values and the integer type will hold 32bit values. The first 4 bytes of the string table contain the number of values in the table as a 32 bit integer, just like the regular string does.
Version 2.08 onwards.
A new keyword has been introduced "flash" that is used after the constant keyword, this applies only to the {} option but will allow the constant to be saved directly to flash. The purpose of this is to allow constant words to be larger than the available program (RAM) memory. This will occur when using large fonts and pictures.
Example:constant PI 3.142
constant version$ "12.449"
constant C1 PI * 2 // uses a previously defined constant
Version 2.06+
constant a$ {0x13,4,7,0xac,0x44, \
33,12,2}
constant b { 1,2,3}
To use the above constants the address of operator is required, thus dump(?a$,32) and dump(?b,32)
Version 2.08+
constant flash Arial80$ {.....}
constant flash Integer {....}
The 'flash' keyword is optional and only applies to integer and byte($) constants and then only to constants that use {}
continue
Description:
This can be used in the while/wend loop. If is is encountered the execution will continue from the start of the while statement.
Example:
while a > b
code...
if get_event() = 1 then
continue
endif
wend
See also:
while
cos (Floating point)
Description:
returns the cosine of a value in radians
Example:
x# = cos(1.570)
x# will now have the value close to 0 as 1.570 is 90 degrees in radians
date$
Description:
a$=date$()
Returns the data as a string in the format: dd/mm/yy ww Where ww is the day of the week. This function may not be available on all devices.
Example:
print date$()
dbl2float (Floating point) Not available from version 2.3
Description:
Converts a double value to a float
Example:
a# = dbl2str(dval!)
dbl2int (Floating point) Not available from version 2.3
Description:
Converts a double value to integer
Example:
a = dbl2str(dval!)
dbl2str (Floating point) Not available from version 2.3
Description:
Converts a double value to a string
Example:
a$ = dbl2str(dval!)
default (select/case/default/endselect)
Description:
See select
diaspect (Devices with a screen)
Description:
diaspect(x)
Changes the screen orientation 1 is landscape and 0 is portrait (default). This will not effect the current contents of the screen, just the items that are placed after this command is issued
diback (Devices with a screen)
Description:
diback(colour)
Sets the background colour. The integer specified in ‘colour’ is a colour number obtained from
dirgb()
Description:
dibl(x) Turns the back light on or off
Description:
dibox(cart,colour)
Draws a box (filled rectangle) x0,y0 is the upper left corner and x1,y1 is the lower right corner.
Description:
dicls(colour)
Clears the screen to the specified colour.
Example:dicls(diinfo(6)) // clear screen to current background colour
dicls(dirgb(0,0,0)) // clear screen o black
dicircle (Devices with a screen)
Description:dicirce(cart,colour)
Draws a circle; the centre is given by x0,y0 and the radius is x1
Example:
dicircle(cart(75,75,20,0),dirgb(63,63,0)) // draws a yellow 20 red circle
dicursor (Devices with a screen)
Description:dicursor(x)
Turns the cursor on or off. Not all screens will have a cursor in which case this function will do nothing.
difont (Devices with a screen)
Description:difont(“string”)
All devices with a screen have a built in font and this is specified by difont(“0”). For devices that have a flash chip then the font can be specified using the block at which the font is stored but as a string. For example if a font s stored at block 25 then difont(“25”) is used.
Fonts can also be specified as a file on the SD Card using the following syntax difont(“filename”). Font files can be created using CodeHeads font file creator and then making a binary file using BV_COM2. Currently there is a limit of 1k per character, if this is exceeded then an error will be given when using difont.
As from version 2.08+ a font can also be a constant name and specified by creating a byte constant. There is a program that will convert .bff files created by CBFG called fp2c, as they can be quite large there is also an option to save the constant directly to flash. To use the constant simply specify the constant name as a sting. As an example if the constant were called System$ then the following would set that to be the new font:
difont("System$")
For further information see the getting started section for the particular device. The text will have information on the various ways of loading a font.
difore (Devices with a screen)
Description:difore(colour)
Sets the foreground colour. The integer specified in ‘colour’ is a colour number obtained from dirgb()
diimage (Devices with a screen)
Description:diimage(“source”,x,y)
Places an image on the screen at co-ordinates x,y from the specified source. The source can be “com1”, “com2”* a file on the SD Card or a memory location. The image must be converted to type MBC before use. The best way to do this is to use BV_COM2 or the free converter tool that can be found on the downloads page here called BMPconvertor.
*com1 and com2 refer to the microcontrollers UART port and not the port used on the PC for communication.
Example:
diimage(“com2”,0,0)
Now send the image using binary the transfer option of BV_COM2. NOTE that "com2" refers to the UART on the BV device and not the COM port on the PC.
diimage("image.bmc",0,0)
This is a file on the SD Card
dimage("pic$",0,0)
In this case a .h file has been created using BV_COM2 (the binary download option with create file ticked) and then it has been converted by hand to a constant, something like:
constant flash pic$ {...... etc. }
diline (Devices with a screen)
Description:diline(cart,colour)
Draws a line from point 1 to point 2 in the specified colour. Point 1 is given by x0,y0 and point 2 by x1,y1
Example:
diline(cart(30,30,50,50),dirgb(63,63,63)) // draws a white line from 30,30 to 50,50
Description:
This defines a variable, all variables must be defined before use. For more information about variables see the language guide.
Example:
dim a$[50], d, v#, p=12
Description:
dipix(x,y,colour)
Draws a pixel at the give point in the specified colour.
Example:
dipix(cart(10,10,0,0),dirgb(63,0,0))
diputs (Devices with a screen)
Description:diputs(x,y,colour,“string”)
Places the specified text at the current position. This offers the control in one statement.
Example:
diputs(x+6,y,dirgb(63,0,0),a$)
direct (Devices with a screen)
Description:direct(cart,colour)
Draws a rectangle x0,y0 is the upper left corner and x1,y1 is the lower right corner.
Description:
colour=dirgb(red,green,blue)
Most commands will expect a single integer number as a colour, this function will convert 3 individual colours to an integer number for those commands. No check is made on the maximum value for r.g or b and so refer to the hardware data sheet for that.
Example:
difore(dirgb(63,63,63)) // sets foreground to white
ditell (Devices with a screen)
Description:x=ditell(<request>)
Returns information about the current font and screen settings, the information returned will depend on the <request> value as follows:
1 height
2 width
3 orientation
4 max_x
5 max_y
6 background colour
7 foreground colour
8 max colour value
9 touch scan rate
ditextpos (Devices with a screen)
Description:ditextpos(row,col)
Positions text at a specified row and column. The row and column start at 0 so the top left hand corner would be 0 0. This command is used for laying out text and actual position is determined by the font in use. See dipixpos for more accurate text positioning.
dipixpos (Devices with a screen)
Description:dipixpos(x,y)
This will move to the pixel position given by x and y starting at 0 0. Maximum x is 239 and maximum y is 319 on screens with a resolution of 240 x 320. It can be used for any text or drawing command but when used for text it enables the text to be positioned exactly. This is useful for getting exact positioning such as under pictures or headings etc.
This will not draw anything, see dipix to draw a pixel.
diup, didown, dileft, diright (Devices with a screen)
Description:diup(x)
This will move the cursor 1 or more (lines, columns) as set by x. The actual position is determined by the font.
dihome (Devices with a screen)
Description:
moves the cursor to the home position
Description:
Lists the current directory. This will only work if an SD card has been mounted
ditext (Devices with a screen)
Description:ditext(“string”)
Places the specified text at the current position. The text colour is determined by the foreground colour.
Description:
Loop structure. The loop will be performed at least once.
Example:
do
code....
until a > b
Description:
dump(address,length)
Used to inspect memory
Example:
dump(?a$,20)
dump(0xa0001000,256)
In the first example the address of the variable a$ is passed to dump and so the contents of a$ including the length word is shown. The second example will display the contents of the given address, in the case of PIC32 this will be a RAM area.
A length of 0 can also be specified, this will output 256 bytes and pause for the user to press space for another 256 bytes.
ensdelect (select/case/default/endselect)
Description:
See select
Description:
<float value> = exp(<float value>)
Returns natural antilogarithm
Description:
fbload(“filename”)
This will create a file on the SD Card and load binary information from the default com port to the card. This can be used for sending from a PC to the SD Card without removing the SD Card first. For correct operation hardware handshaking MUST be enabled. See comrts and comcts
Description:
type=fcblock(block)
When fcsave on BV_TOOLS are used the type of saved data is written to the first byte in the first block. This will return what type is stored in the specified block. Note that it is just the first block that determines the data type and so if an image for example is stored over several blocks the other blocks will simply return a not empty type. The return type is a byte but when printed will give the following:
'b' This is a bitmap block
'm' Macro
'f' Font created with BV_TOOLS
'F' Font created with fcsave – has a slightly different format.
'U' This is a configuration block and will always be block 0
'n' Unknown none blank block – only the first byte is tested if this is not blank (0xff) the the whole block is assumed to contain something.
'e' Empty block – most likely. Only the first byte is tested and if it is 0xff it is assumed that the whole block is empty
Special Note: Not all devices use this notation so it is better to refer to the acutal device data sheet or user guide for this particular command.
Description:
error=fcd(“directory”)
changes the current directory to requested directory, relative path names and disk drive numbers can be used. Check for return value as it will return an error code if the operation is unsuccessful.
Example:
fcd("0:/") // changes the current directory to top level of disk 0
fcd(“fred”) // changes the current directory to fred in the current directory
Description:
fcerase(startBlock,endBlock)
Erases a specified block range. Individual bytes cannot be erased for this type of memory. A block is 4096 (4k) bytes and starts at 0. Normally for a 16Mb Flash the block range is 0 to 499
Description:
error=fchdrive(x)
Changes the current disk x is a number with 0 being the default. For this to work the hardware must support more than one drive
Description:
fclose(f)
Closes a file and frees up the resources taken by that file. The f is the file descriptor obtained when the file was opened. It is important to close (or flush) files open for writing as this will write any unsaved information back to the disk.
Description:
x=fcread(s$,adr,size)
Reads the contents of the Flash chip into the string variable starting at address for length bytes. Returns the number of bytes read. A string is used to ensure that the number of bytes does not exceed the space available. If 0 is returned then there was some error. If a size larger than the string is given then the string size will be used.
Example:dim a$[128] print fcread(a$,0,120) To view the contents of the string use dump as follows: dump(?a$,120) Typical output: a0001c00 84 00 00 00 55 aa 00 00 00 3c 3c 3c 3f 3f 3f ff ....U.......???. a0001c10 00 ff f0 00 40 01 30 90 20 00 21 00 50 00 51 00 ....@.0...!.P.Q. a0001c20 52 00 53 00 01 ff 64 00 00 41 01 ff 00 00 00 00 R.S...d..A...... a0001c30 66 01 00 0a 33 33 4f 40 66 66 24 40 00 00 02 00 f...33O@ff$@.... a0001c40 00 00 ff ff 00 ff ff ff ff ff ff ff ff ff ff ff ................ a0001c50 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................ a0001c60 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................
In the above the first 4 bytes are not part of the data returned but the size of the string 0x84 is 132 bytes. The discrepancy between the 128 requested is due to word alignment.
Description:
fcrecall(block,x,y)
This is only available for hardware that is fitted with this flash and also a screen, e.g. the BV514. It will recall an image from the flash and display on the screen at the given co-ordinates. The block is a number where an image of font is stored, for a 16Mb flash this will be in the range of 1 to 499 for images and 10 to 499 for fonts. To recall a font the x and y should still be specified but can be set to 0. Thus if block 80 contained a font then fcrecall(80,0,0) would set that font as the current font.
There are two types of font file format one is used by BV_TOOLS and the other used by fcsave. This function can handle both.
Description:
fcsave(“source”,”type”,block)
Saves a stream of binary data to the flash, the source is either “com1” or “com2”. Type is “f” for font data and “b” for bitmap data.The block is the starting block of the AT Flash memory. The block must have been erased first otherwise the save will not work properly.
In order to save a binary stream it is important that the RTS-CTS is on.
Description:
x=fcsize
Returns the size of the on board Flash chip in blocks, a block is 4096 (4k) bytes
Example:
print fcsize
Description:
fcwrite(address,size,s$)
Writes the contents of the string to the flash for a given size in bytes. The bytes written will only include the contents of the string and not the string size.
The address must be an erased part of memory otherwise an attempt will be made to overwrite what is already there giving unpredictable results.
Description:
error=fdel(“name”)
Deletes a directory or file
fdirlist (File System) Added version 2.30 build 86
Description:
error=fdirlist(a$,position)
Gets the name of a file and its details in the current directory. This can be used for creating a directory list or examining the files within the directory. The file details are returned in the string and the position is the position of the file in the list.
The function will return 1 on error and 0 on success. An error is if the position requested is outside the number of files in the directory, the first file begins at 1.
Description:
x=feof(f)
returns a none zero value if the file has reached the end.
Description:
error=fflush(f)
The fflush function performs the same process as fclose function but the file is left opened and can continue read/write/seek operations to the file. This is suitable for the applications that open files for a long time in write mode, such as data logger. Performing fflush of periodic or immediately after fwrite can minimize the risk of data loss due to a sudden blackout or an unintentional disk removal. However fflush immediately before fclose has no advantage because fclose performs fflush in it. In other words, the difference between those functions is that the file object is invalidated or not.
Description:
error=ffree(<disk>,?x)
error=ffree(<disk>,*x) post version 2.3
Obtains the number of bytes available on the disk, the answer is returned in the variable x and is in KB. Disk is a drive number normally 1 or 0.
Example:
dim a
print ffree(0,?a)
print ffree(0,*a)
print a
Description:
byte=fgetc(file)
Reads one character from the given file.
Description:
error=fgetcwd(s$)
Gets the current working directory and returns it in the string variable.
Description:
error=fgets(s$,file)
Reads a string into the variable s$ provided. The maximum bytes that will be read will be the size of the string.
error = 0 on okay
Description:
error=finfo(“filename”,s$)
gets the information about a file as a string record. This can also be used to see if a file exists by checking for the returned error. The information is returned as a string in the supplied string as a record as follows:
Byte Position Description
0 to 4 File attributes
6 to 9 Year
11 to 12 Month
14 to 15 Day
17 to 21 Time
23 to 32 Size
33 – end Name
Example:
dim a$[80],size
finfo(“fred”,a$)
size = mid$(a$,23,10) // size of file
Description:
flclear(<save number>)
Clears the flash in oneof two ways: using flclear(0) will clear all of the user flash, flclear(1) will clear the last saved page of flash.
Description:
flerase(page_address) Will earase a page of flash memory. The page size for the MX170 is 1k and MUST be on a page boundary (0x0, 0x400, 0x800, 0xc00)
Example:
This is intended for storing non-volatile information. Tos see how it may be used see the example in libraries.
Description:
flstore(address,32bit word) This will store the word at the given flash address, for predictable results the address contents must be blank (0xffffffff). It is not possible to erase just 1 address location. The erase function erases 1k at a time.
Example:
This command is intended for saving non-volatile data. See the library example for best use.
Description:
fload(“filename”)
Loads a function or set of functions from the given file. The file must exist on the SD Card. Functions will be loaded on top of existing functions.
float2dbl (Floating point) Not available from version 2.3
Description:
d! = float2dbl(a#)
Converts a float to double
Description:
x = float2dbl(a#)
Converts a float to integer
Example:
print float2int(12.50)
Description:
a$ = float2dbl(a#)
Converts a float to string
Description:
flsave([“”][“item”])
Saves the current memory contents to flash. This will show a save number which is used in flclear. The action of this is to effectively move the contents of RAM into Flash. There are two options, a null string “” and an item (function, variable or constant). When a null string is specified all of the loaded items will be moved to Flash, when an item is specified only those items including and after that will be moved into Flash.
function aa()
if lookup("xx1") = 0 then
print "loading x1.bas functions"
fload("x1.bas")
flsave("xx1")
endif
if lookup("xx2") = 0 then
print "loading x2.bas functions"
fload("x2.bas")
flsave("xx2")
endif
endf
In this example the first function in the file x1.bas is called xx1. If it does not exist then fload(“x1.bas”) will load all of the items in x1.bas on top of anything else already in RAM. The action of flsave(”xx1”) will move all of the functions just loaded into Flash, effectively removing
flsys (removed 2.08 onwards, see user guide)
Description:
flsys(<identifier>,value)
Changes system settings. WARNING: Take care when using this command as applying some values will render the system inoperable. Full details of this command can be found in the user guide.
Description:
Displays information about the current Flash memory
Example output:
Page size 4096
Flash start 0x9d042000
Current start 0x9d042000
Current free space, bytes 253948
Save number 0
Description:
error=fmkdir(“directory”)
Creates a directory
Example:
fmkdir(“fred”) // creates directory fred in the current directory
Description:
error=fmount(x)
Mounts a disk
Description:
file=fopen(“name”,”mode”)
Opens a file and returns a file descriptor. The file descriptor will contain an address to the file block and it is this descriptor that will be used in all subsequent file operations. Name is the name of the file which should be a string and mode is also a string and one of the following:"r" Open a file for reading. The file must exist.
"w" Create an empty file for writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file.
"a" Append to a file. Writing operations append data at the end of the file. The file is created if it does not exist.
"r+" Open a file for update both reading and writing. The file must exist.
"w+" Create an empty file for both reading and writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file.
"a+" Open a file for reading and appending. All writing operations are performed at the end of the file, protecting the previous
The function will return 0 if the operation fails, the programer should check for this.
Description:
The for next loop is used when a certain amount of iterations are required, there is also an accessible index which can be put to good use. The index used for the loop must be defined first.
for j=1 to 5
int j
print j
next
for j=-10 to -20 step 2
print j
next
The ‘step’ statement is optional but must be used for negative numbers as the default step is 1 if it is not specified. Integer only variables are used for this. If floating point is required then use the while / wend construct.
Description:
forget(“function”)
Functions are compiled one after the other. This will forget all functions including and after the one specified.
Description:
s$=format$(“format string”,<value>)
This is intended for formatting numbers or strings. The format string is similar to the one used for 'printf' in the C language. Please look there for more details.
NOTE: There are restrictions with this function:
1) It will only accept two parameters and so will only do one format at a time, you cannot specify more than one format specifier. For example format$(“ %d %d”,12,12) is not allowed because that would be three parameters.2) Another restriction is that the second parameter cannot be an expression. This function is likely to be updated in future releases.
Example:
dim f#=123.779
print format$(“this number %f is unformatted”,f#) // result: this number 123.779 is unformatted
Some format options:
%f.2 format to 2 decimal places
%e uses scientific notation
%g uses scientific or normal notation whichever is shorter
%x prints the number as a hex value e.g 7b
%c prints as a character, print format$(“%c”,65) will output A
%%10u prints as unsigned integer padded with 10 spaces at the front
Description:
position=fpos(file)
Returns the current file pointer position, start of the file is 0.
Description:
error=fread(s$,length,?count,file)
error=fread(s$,length,*count,file) post version 2.3
Reads from an open file into the string provided for the requested length. The actual byte read are placed in to count. Count is an address of a variable provided by the user.
NOTE although a string is used as the buffer all byte values will be read into the string so the string may not be a string at the end of the operation.
Lists the contents of a file, note for simplicity a check at the end for count is simply 0 and so extra content (the string residue) will be printed out.
function list(fname$)
dim f,a$[128],count,er=0
f=fopen(fname$,"r")
if f <> 0 then
while er = 0
er=fread(a$,100,?count,f)
er=fread(a$,100,*count,f)
if count = 0 then
break
endif
print a$
wend
endif
fclose(f)
endf
Description:
error=frename(“oldname”,“oldname”)
Renames a file or directory
Description:
frun(“filename”,”function”,”forget”)
This will load the functions contained in the file given by “filename” into ram and then run the function specified in the second parameter. The third parameter can be a function, constant or variable name or “”. If a null string is sent (“”) then all of the existing functions, constants and variables (items) will be removed before loading the new file. If however an item is specified for “forget” then that item and items after that will be removed leaving behind any previous items. This is useful for keeping functions or variables that may be needed when the new file is loaded.
dim a,b
function foo()
....
a=15
endf
function foo1()
frun(“menu2.bas”,”start”,”foo”)
endf
In the above example the functions in menu2.bas will be loaded and all of the items in this program will be removed except the variables a and b that will be availabe to the new program. A will also be set to 15. This could indicate something to the start function that will be run when menu2.bas is loaded.
It should be noted that menu2.bas will not compile stand alone as it does not have the variable 'a' it will error saying variable not found. However using fload or in this case frun the variable does exist and so it will compile okay when loaded.
Description:
error=fseek(pos, file)
Moves file pointer to an absolute position in file. An attempt to move past the end of the file in read mode will not generate an error but just move the pointer to the end of the file. In write mode the file will be expanded to accommodate the new size.
//Reads a file 30 bytes along and prints the next 10 bytes
function sk(filename$)
dim f,a$,count
f=fopen(filename$,"r")
if f = 0 then
print "\ncant open " filename$
return
endif
if fseek(30,f) <> 0 then
print "problem with seek"
return
endif
fread(a$,10,?count,f) pre version 2.3
fread(a$,10,*count,f)
print "read 10 bytes 30 along:"
print a$
fclose(f)
endf
Description:
x=fsize(f) returns the size of the file.
Description:
error=ftruncate(f)
The ftruncate function truncates the file size to the current file read/write point. This function has no effect if the file read/write pointer is already pointing end of the file
Description:
Creates a function, see Language Guide for further details
Description:
error=fwrite(s$,length,?written,file) pre version 2.3
error=fwrite(s$,length,*written,file)
Writes the contents of the string to the file for a given length or the length of the string whichever is the smaller. The number of bytes actually written will be returned in the variable supplied at ?written. The string can contain nonprintable characters.
Example:
/// creates a file, blanks and writes to it
function wtest()
dim er,f,written
dim j,b$[30]
// create a file
print "creating file fred"
f = fopen("fred","w")
if f = 0 then
print "error creating file fred"
return
endif
// write some information
for j= 1 to 10
b$=j+" Hello Fred\n"
er=fwrite(b$,strlen(b$),?written,f)
er=fwrite(b$,strlen(b$),*written,f)
if er <> 0 then
print "problem writing to fred"
return
endif
next
fclose(f) // this also saves
endf
Contents of file:
1 Hello Fred
2 Hello Fred
3 Hello Fred
4 Hello Fred
5 Hello Fred
6 Hello Fred
7 Hello Fred
8 Hello Fred
9 Hello Fred
10 Hello Fred
Description:
returns a hex string of a value
Example:
print hex$(12)
Description:
Used for loading programs (functions) into flash. This is used by other programs such as BVSerial.
hload(1) will send 'cold()' first
hload(0) will not
Example:
print hload(1)
Description:
i2cclose(channel)
Closes an open channel, this may be used to free up the ports that are normally assigned to the I2C bus.
Description:
result=i2cgetc(<channel>,?v,timeout,last) pre version 2.3
result=i2cgetc(<channel>,*v,timeout,last)
This will receive a byte into v from a slave device. The correct protocol for receiving is to set last=1 when it is the last byte to be received. The timeout value is arbitrary and depends on the slave device. The actual time value is approximately 0.10us * t. A value of 10000 will work for most devices.
Result values:
0 ack received – good
1 ack not received – bad
2 time out error
Example:
dim v
r = i2cgetc(1,?v,100,1)
r = i2cgetc(1,*v,100,1)
print v
Description:
i2copen(<channel>,<speed>)
This opens an I2C channel at a given speed. See the hardware data sheet for the device as if it already uses I2C the channel will already be open. The channel is a number normally 1 or 2 but some controllers may have more. The speed is the bits per second. The normal speed I2C is 100000 and high speed is 400000
Example:
i2copen(1,100000)
Description:
result=i2cputc(<channel>,value)
Sends one byte <value> to the I2C bus.
Result values:
-1 on collision
1 when ACK received from slave – bad
0 when NACK received from slave – good
Description:
error=i2cputs(<channel>,”string”)
Sends a string to the I2C bus. error = 0 on okay
Description:
error=i2crestart(<channel>,<address>)
This is simply a stop followed by a start and is normally used where a device needs a command followed by a read as in memory devices.
error=0 if start okay.
Description:
i2cscan(<channel>,Start_address,End_address)
This will scan the I2C bus for any devices within the range given and return with an address of a found device. This is very useful for detecting if a device is connected to the bus before use.
// to see if device 0x42 is on the bus
if i2cscan(1,0x42,0x42) = 0x42 then
print "\ndevice found"
endif
Description:
error=i2cstart(<channel><address)
This will send the start condition followed by an address. The address is an 8 bit value, in other words the least significant bit should contain the read-write bit. So sending 0x42 will be a write operation and sending 0x43 will be a read operation.
error=0 if start okay.
Description:
i2cstop(<channel>)
Sends a stop condition.
Description:
Branch structure. Used for decision making, see the user guide for more details. Note that the 'then' is optional
if a > b then
code...
else
more code...
endif
if a > b
code...
endif
int2dbl (Floating point) Not available from version 2.3
Description:
d! = int2dbl(x)
integer to double
Description:
f#=int2float(x)
Converts a floating point value to an integer
Example:
print int2float(10)
Description:
s$=int2str(x)
Converts an integer to a string
Example:
print int2str(10)
Description:
irclear()
This clears the whole of the user table.
Description:
irset(<interrupt>,<mask>,”function”)
This will install the “function” into the interrupt table. The function will already exist and can be any user or system function with certain restrictions, see later. The interrupt is an interrupt register address, one of the flag registers (e.g. IFS0). The mask will have the relevant bit set that represents the desired interrupt.
When the interrupt services the routine it will check the flag against the mask (flag & mask). If the flag is set, which will be caused by an external event, then the function supplied will be executed. After execution of the function but before leaving the interrupt the flag is cleared so the user does not need to do this.
Description:
let a = 12
This is optional and only really used internally.
Description:
list(x)
This will list the functions that exist in Flash and or RAM depending on the value of x.
x=1 will list the functions and their addresses,
x=2 will output the functions and keywords in a suitable format for the Pspad syntax highlighter.
example output for list(1)
Address Hash Name
9d032d58 2f3e7e04 frename
9d032d34 65539b09 fmkdir
9d032d10 5c0a3bb4 finfo
Description:
<float value> = exp(<float value>)
Returns natural logarithm
Description:
lookup(“item_name”)
This will return the address of an item name if it exists or 0 if it doesn't. An item is a function, keyword, constant or variable. The main purpose of this function is to check to see if a function exists.
Example:
print hex$(lookup(“flclear”))
Description:
x = max(a,b)
Returns the largest number a or b
Description:
s$=mid$(“string”,start,length)
Chops a section out of a string, start begins at 0
Example:
dim a$
a$=”hello fred”
print mid$(a$,6,4)
The above will print “fred”
Description:
x = min(a,b)
Returns the smallest number a or b
Description:
Toggles the sign bit of a value
Example:
print negate(12) // will print -12
print negate(-12) // will print 12
Description:
Part of for/next.
See:
for/next
Description:
x = peek(<address>)
Returns the contents of an address as a 32 bit integer value. As an alternative @ can be used but not for expressions, see the Language Guide.
Description:
x = peek(<address>)
Returns the contents of an address as an 8 bit value
Description:
peek(<address>,<value>)
Sets the specified address to the given value. This will set a 32 bit word.
Description:
peek(<address>,<value>)
Sets the specified address to the given value. This will only set the byte of the address that is being pointed to.
Description:
x=pos(“str1”,”str2”)
Returns the position of the start of string 2 within string 1 beginning of string is 0. Returns -1 on no match.
Example:
ddim a$
a$=”hello fred”
print pos(a$,”fred”) //The result returned is 6
print pos(a$,”joe”) //The result is -1
Description:
<float value> = exp(x,y)
Returns the power x to the power of y
Description:
print <expression>[,:]
This is the very basic print and is simple to use. It will be associated with the default UART so is useful for development and debugging. To gain access to the other UARTS (if any) use the additional functions in this section. Unlike the standard BASIC syntax this will NOT automatically put a CR on the end, this must be explicitly done with “\n”.
Example:
print “hello”
print “hello\n” // adding “\n” will add CR
print a$,b // b will be printed a tab width away from a$
Description:
value (integer) = rand(min,max)
Returns a random integer value between the maximum-1 and minimum values supplied.
Description:
Performs a system reset, this is exactly the same as a hardware reset.
Description:
return <x>
Used to leave function early or used where a function returns a value
select (select/case/default/endselect)
Description:The expression inside the select statement and the expressions following the case statements may be values other than integers, however they will all be evaluated as integers.
Break and default are optional. If break is left off then the statement will execute the default code as well as the matched code.
select(expression)
case(expression)
code....
code....
break
case(expression)
code...
break
default
code..
endselect
Example:
select(k)
case(10)
do_lf()
break
case(13)
do_cr()
break()
endselect
Description:
setdate(y,m,d,dow)
Sets the date, use only 2 digits for the year. The dow is the day of week number, this is an arbitrary number but normally Monday is 1
Example:
To set the date to Tuesday 12/3/2014 setdate(14,3,12,2)
Description:
settime(n,m,s)
Sets the time, use 24 hour notation, i.e. setting the time to 5:15 pm will be settime(15,15,0)
Description:
returns the sine of a value in radians
Example:
x# = sin(1)
x x will now have the value 0.841
Description:
odata=spi(idata)
This is the raw data read and write – because SPI does it both at the same time. To read a byte without writing set the idata to 0xff, thus odata=spi(0xff). To read data without writing just ignore odata. NOTE this function is for channel 2 only and is available because on some MX3 devices the channel is used for the SD Card or serial flash memory.
Description:
spirate(rate in Hz)
Sets the SPI clock speed, this by default is set to 10MHz as most SPI SD Card interfaces will not go any faster. The PIC32 processor is capable of going much faster.
Example:
spirate(5000000) // sets rate to 5MHz
Description:
float = sqrt(<expression>)
Returns the square root of an expression
Example:
x#x# = sqrt(9)
x will now have the value 3
Description:
startrtc
This is called at reset and makes sure that the RTC is running. There is no need to call this from a function.
str2dbl (Floating point) Not available from version 2.3
Description:
Converts a string value to a double value
Description:
Converts a string value to a float value
Example:
print str2float(“12.50”)
Description:
Converts a string value to an integer value
Example:
print str2int(“1250”)
Description:
x=strlen(“string”)
Returns the length of the string, excluding the terminating 0
Example:
prprint strlen(a$)
This returns the length of the string inside the buffer. To see the actual size of the buffer use peek(?a$). For example if a string is defined as follows:
dim a$[50]
s$=”fred”
The srtlen(a$) will return 4 but peek(?a$) will return 50. The value is the length of space allocated to the buffer.
NOTE: the result may be higher than expected as when a buffer is allocated it goes to the nearest boundary.
Description:
Gives information about the current system settings. The output of this function is subject to change
Description:
returns the tangent of a value in radians
Example:
x# = tan(1)
x will now have the value 1.557
Description:
An optional part of the if/then/else/endif structure, see if/else/endif
Description:
x=tick()
Returns the value of the CPU core timer. This is incremented at the rate of 1mS and is reset to 0 on reset.
Description:
a$=time$()
Returns a string with the time values, the string format is hh:mm:ss
Description:
Initiates a text transfer load using a simple ACK protocol. This will compile any functions into RAM and is the main mechanism for development. See the Language Guide for a full explanation and for a practical guide see the tutorial on loading.
Description:
s$=token$(a$,?position,'delimiter') pre-version 2.30
s$=token$(a$,*position,'delimiter') post-version 2.30
This will extract a token from a string a$ starting at the position given in position. The delimiter is an integer that contains any character to determine the end of the token. The value of ?position will be updated to point to one past the delimiter and so a variable address MUST be passed here. When the input string is exhausted or the value of position is greater than the length of the string, position is set to -1.
This function is useful for extracting input from a string of options.
Example:
function split(a$[80])
dim p=0
while p >= 0
print "\n",token$(a$,?p,',')
print "\n",token$(a$,*p,',')
wend
endf
In the above example the result of this:
split("hello,fred,and bob,sally")
hello
fred
and bob
sally
Each time token$ is called variable p is updated until it reaches the end of the string when that happens token$ will set the value of p to -1.
Description:
Converts a string to lower case
Example:
print tolower$("Fred") // prints fred
Description:
Converts a string to upper case
Example:
print toupper$("Fred") // prints FRED
Description:
x=tu()
This must be called before any co-ordinates can be obtained. It does two things, first it returns 1 if the screen is being touched at the time it was called and second it will set x and y so that the co-ordinates can be read.
Description:
tucalibrate()
Calibrates touch screen. The results from this will depend on the type of screen but will probably need saving.
NOTE: Before using make sure that the screen aspect is in portrait mode . e.g.
diaspect(0)
tucalibrate()
Description:
x=tuhit(cart,x,y)
This is used for detecting if an area of the screen has been touched, for example has a button been pressed. Cart contains a co-ordinates defining a rectangular area and x will be set to 1 if x and y are within that area.
Example:function x() dim box!=cart(10,10,100,50) print tuhit(box!,15,20) print tuhit(box!,50,60) endf
The above will print1 and 0 because 10,20 is within the defined area and 50,60 isn't.
Description:
tuset(<calibration scring>)
This will set the screen calibration to values passed in the calibration string. The sting consists of 7 long variables and is therefore itself 56 bytes big. The string is obtained from tuget(). Normally the sting obtained from tuget() will be saved onto the SD Card but it can also be saved to flash using 'constant {}' When saving to Flash using constant, dump will be needed.
Example:
To save the calibration to Flash instead of the SD card:
dim cal$[60]
cal$=tuget()
dump(?cal$,64)
A0001C10 40 00 00 00 75 58 FA FF 4E 12 00 00 5D 6F D7 0A @...uX..N...]o..
A0001C20 85 EB FF FF 40 4F 07 00 EB 9B 00 97 3A A1 B5 FF ....@O......:...
A0001C30 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
A0001C40 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
constant cal$ {0x40,0,0,0,0x75,0x58...... etc.
The technique is to dump the contents of the variable and then build it manually into a constant statement.
Description:
tuscan(<rate>)
Most touch screens will scan the touched point several times in order to obtain an accurate location. This sets the number of times that takes place.
Description:
x=tuxy(?x,?y)
This is called to obtain the x,y co-ordinates of the screen when it has been touched. It will return 1 if the co-ordinates are valid. It if it returns 0 then the co-ordinates will contain some random value.
The actual co-ordinates must be obtained first by using tu. The co-ordinates x,y are passed to the function as addresses.
function x()
dim x,y,r
while comkey?(2) = 0 // get out if key pressed
if tu() = 1
r=tuxy(?x,?y)
print "\nr=" r,"x=" x,"y=" y
endif
wend
endf
Description:
Looping structure see do/until
Description:
wait(<milliseconds>)
halts the program for a specified number of milliseconds. The timing is approximate.
Description:
This loop makes the decision at the start of the loop in the while statement and must be terminated by wend.
Example:
while j > 5
.. some code
wend
It is of course up to the user to make sure that there is a condition which causes termination unless the loop is required to go on forever.
x0,x1,y0 & y1 Not available from version 2.3
Description:
These functions return a co-ordinate from a double. What they in fact do is return a 16bit portion of a double word as follows:
x0() bits 61:48
x1x1() bits 47:32
yo() bits 31:16
y1() bits 15:0
Example:
ccoord = x0(d1)