Support : Industrial : AIRcable AIRmotes Programming Handbook : PART 3

PART 3: Built-in Functions and Interrupt Routines

The BASIC interpreter accepts three types of instruction:

• Built-in Functions
  • General-purpose Input and Output Functions
  • File System Functions
  • Bluetooth Functions
  • String Functions
• Interrupt Routines
• Command-Line Interface
  • Built-in Commands
  • Editing
  • Interactive Use of Built-in Commands

Interrupt routines and functions are built-in and cannot be changed. An interrupt routine is executed only in response to a specific event. Built-in functions are called as an assignment to a BASIC variable. Commands are executed as a normal program line of code.

Capitalization is fundamentally important as the interpreter will not generalize. "A" and "a" are not the same character. Interrupt routines are preceeded by @ and are Capitalized. Functions are NOT capitalized. Commands are written in all CAPS.

Built-in Functions

Built-in functions are implemented in native code and cannot be changed. They fulfill time-critical functions such as Bluetooth functions, external input and output functions, file-system functions, and others.

All built-in functions are called as an assignment to a BASIC variable. They can have one parameter or no parameters. Functions are all lower case. A parameter is defined as any one of the following:

• a string (S)
• a variable (V)
• no parameter (N)

Examples are:

The string index parameter is a substring parameter to the function.

Each function has a particular parameter. This is the list of built-in functions:

General-purpose Input and Output		File System Functions		Bluetooth Functions		String Functions
pioin	V	open	S	slave	V	atoi	S
pioout	V	append	S	master	N	a2toi	S
pioget	V	close	N	inquiry	V	xtoi	S
pioset	V	read	V	cancel	N	x8toi	S
pioclr	V	write	V	link	V	hex8	V
pioirq	S	delete	S	unlink	V	hex16	V
psget	V	size	N	disconnect	V	strcmp	S
psset	V	exist	S	name	S	strlen	S
uartcfg	V	seek	V	message	S
baud	V	info	V	ftp	S
uarton	N	rename	S	modemctl	V
uartoff	N	erasefs	N	getaddr	N
date	S	load	S	getuniq	V
reboot	N			status	N
nextsns	V			success	N
sensor	S			getname	S
setdate	S			maxpower	V
uartoff	N			bizcard	S
uarton	N

General-purpose Input and Output Functions

nextsns: This function schedules the reading of the internal sensors within the number of seconds provided as a variable. When the reading were taken, the interrupt routine @SENSOR will be called. This happens only once. Afterwards a next reading has to be scheduled again. nextsns0 turns this function off.

sensor: Returns the last-read value of the analog input to the variable used in the assignment. The values range from 0 to 1800. When a correction factor (@0008 in config.txt) is used, the values can be calibrated to the actual reading. It is usually expressed in millivolts, depending on the hardware. In addition, the temperature reading is placed into the string given as a parameter, and the relative signal strength indicators for the incoming slave connection and the outgoing master connection. Each number takes 5 character positions in the string: E.g. "1850 27 1 -1"

pioin argument: The function configures the port as an input. An expression (a number or a variable) that specifies the port number. Port numbers 1 to 6 can be used.

pioout: Configures the port as an output.

pioget: Reads the value of the port and returns it into the variable specified.

pioset: Sets the port active (high). If the port is configured as an input, it activates a
pull-up resistor on that input.

pioclr: Sets the port to inactive (low).

pioirq: This function gets a string like "P000100". It starts with a 'P' and follows with '0' and '1' for the 6 available digital input pins. This function activates the input PIN to create interrupts when a change occurs. See @PIO_IRQ interrupt routine below.

date: This function writes a date string into the string given as a parameter, e.g., "20050531T192100Z"

reboot: This function will reboot the processor in 2 seconds. All connections will be terminated.

uartcfg: Configuration of the UART interface is coded in one integer value ranging from 128 to 255. The 8 bits are coded like this: 1PPSBBBB. For even parity, set 0x40; for odd parity, set 0x20; for two-stop bits, set 0x10. Baud rates are enumerated: 0 is 1200 baud, 1 is 2400 baud, 2 is 4800 baud, 3 is 9600 baud, 4 is 19200 baud, 5 is 38400 baud, 8 is 115200, and 12 is 1382400 baud.

baud: A simpler function that just changes the baud rate of the UART to the baud rate specified in the variable. Baud-rate values are specified in 100-baud values, such as 96 for 9600 baud and 1152 for 115200 baud. e.g. "A = baud 96"

break: The break command creates a break condition on the UART port. The TX line will be held low for a longer period of time.

psget: This command allows access to the configuration of the AIRmote devices as stored in the file config.txt. The argument is the key number as described in the config.txt file format. The result is placed in the string given that describes the configuration key in the same format.

psset: Enables writing to the configuration. Argument is the length of the string.
The string that will be stored in the configuration must have the correct format to be successful.

setdate: Function to allow to adjust the clock. The string parameter contains a valid date string such as 20060123T085854Z.

uartoff: This function decouples the UART input from the BASIC input handler. If the UART port is connected to a streaming data source the system has to process the input even if no BASIC application receiving the input. Therefore it is helpful to improve performance to switch off the UART if not needed.

uarton: This function connects the UART input stream with the BASIC input handler system again. Normally these function are not required, since the UART input stream is normally connected.

File System Functions

A BASIC program can have one open file. A file name can be up to eleven characters long. The file system holds four files.

open: It opens the file and sets the file pointer to the beginning of the file. Parameter is a string that specifies the name of the file.

append: Opens the file specified but puts the file pointer to the end of the file. If the file does not exist, it will be created.

close: Closes the open file. If the file was overwritten at this time, the file system cleans up unused blocks and recalculates the size.

read: The parameter specifies the number of bytes to be read. The result will be placed into $0. The function returns the number of bytes read. A maximum of 32 bytes can be read. It returns zero when the end of the file has been reached.

write: Writes the number of bytes from $0 into the open file. It returns the number of bytes written.

delete: The file specified will be deleted from the file system. The file must be closed before.

size: Returns the number of bytes the opened file contains. The file has to be opened.

exist: Returns non-zero if the file with the name specified already exists in the file system.

seek: Places the file pointer to the specified byte number in an opened file.

info: This parameter is an integer from 0 to 3 specifying the index number of a file in the file system. The file's information (name, size, date) is put as a string into $0.

rename: A file that has been opened can be renamed to the string given. It is only successful, if a file with the new file name does not exist.

erasefs: Deletes the whole file system. All data in the files are lost. The files AIRcable.bas and config.txt are not erased. No parameter.

load: This function allows to load a BASIC program from the file system into the BASIC interpreter. The parameter is the name of the file to load. Lines specified in the file will overwrite lines in the existing BASIC program. If @ERASE is in the file, the existing BASIC program will be erased. Otherwise BASIC programs can be partially loaded using this function. Existing lines should be deleted when not used using just the line number and a space in the new file.

Bluetooth Functions

The BASIC program controls the Bluetooth access and the serial-port profile SPP.

slave: This function opens the Bluetooth device for incoming serial connections. The parameter specifies the number of seconds the port stays open. After that, the port closes again and the application has to call "slave" again. Note that the UART and the slave SPP port are not being connected automatically. Use the link command. As soon as another Bluetooth device successfully connects to this device, an interrupt routine @SLAVE will be called.

master: Creates a connection to a SPP channel of another Bluetooth device. The parameter is the Bluetooth address as a string. The parameter must be in $0. When the connection is successful, the interrupt routine @MASTER is called.

inquiry: To find other Bluetooth devices in range, call this function. The parameter is the number of seconds the inquiry is active. When a Bluetooth device is found, an interrupt routine @INQUIRY is called.

cancel: This function is used in the inquiry-result interrupt routine to stop further inquiry results from being scheduled.

link: Use this to link either two of the three available channels together so they route data through. The parameter is a number that determines which channel to link. For example: 1 links the UART and the SLAVE channel, 2 links the UART and the MASTER channel, and 3 links the SLAVE and the MASTER channel for range-extender functions.

unlink: This function disconnects the channels. Use the same values to determine which one should be disconnected.

disconnect: This command disconnects one of the over-air connections. The parameter disconnects the SLAVE connection; non-zero disconnects the MASTER from the other Bluetooth device.

name: This command configures the user-friendly name of the Bluetooth device that is displayed during the inquiry process. The parameter is a string. The default is the configured name in the config.txt file, a space, and the unique 5-digit number generated.

message: This function allows an OBEX vNote transfer to another Bluetooth device. The content of the string parameter will be placed in the BODY part of the vNote to be sent. The 12 digit Bluetooth address to where the message is sent is in $0 as a string.

ftp: This function allows the transmission of a file in the e2fs file system to another Bluetooth device. The parameter of the call is the file name on the remote device. The address to which the file is being sent is a string in $0. The file that is to be sent has to be opened by the e2fs open call before the ftp function call. This example sends a file called test.txt to another machine. The file created there is named "from.txt"

modemctl: To send a modem-control command to a current active SPP connection, this function can be called in response to a change of the DTR input line on the AIRcable Industrial Male device. The value 0 as a parameter sets the modem-control, a 1 resets it. This command should not be used when two SPP connections are active.

getaddr: To receive our own Bluetooth address as a string in the $0 variable, call this function with no parameter.

getuniq: This command returns the AIRmotes own unique number that is calculated from the unique Bluetooth address to distinguish multiple AIRmote devices. A string index number can be given as an argument. The unique number will then be printed as a string to the string variable given as a parameter. This command is useful for the name change command to add a unique number to it.

status: The function returns the state the Bluetooth processor is in. 5 states are defined encoded into one decimal number. If an inquiry process is busy, 10000 will be added to this number. If a message transfer or an ftp transfer initiated by the AIRcable is in progress, 1000 will be added. If the device receives an FTP or a message, 100 will be added. If a master connection is established, 10 will be added and if a slave connection exists, 1 is added to this status number. This information can be used to determine when an operation is finished.

E.g. This subroutine waits until an FTP transmission completes.

success: The function returns if the last operation (ftp or message) succeeded or not. If the return value is 1 then the operation was a success. It is -1 if an error occurred. It is set to 0 if a connection could not be established.

getname: Returns its own name of the device (Bluetooth friendly name) in to the given string.

maxpower: Allows the adjustment of the maximum RF output power for all communications. Normally this is set by the configuration parameter @0004 = 0000 0006. It may be useful to determine the range or distance between two Bluetooth devices by establishing a link and then reducing the transmission power and measure the RSSI parameter.

bizcard: This function sends a business card from an open file to another bluetooth device. The argument given is the BT address. The file to send must be opened before. The contents should follow the OBEX specification of business cards. Some devices will not accept this if the content is not correct. The OBEX PIM item transfer for vCards will be used to sent the content.

This is an example for a vCard accepted by PCs, PDAs and cell phones:

String Functions

atoi: This function turns a string specified into an integer. The limit is 16 bits. If the characters are not numbers—or during overflow—the result is zero.

a2toi: This function turns two number characters into an integer value. A string index variable as a parameter provides the start point. No termination is necessary.

xtoi: This function turns exactly four hex numbers in a string into an integer value. A string index variable can be used as a parameter.

x8toi: This function turns exactly two hex numbers into an integer value.

hex8: This function prints a variable given as two hex numbers into $0. For example: if B contains 27, then A = hex8 B will print "1B" into the first two positions of $0.

hex16: This function prints a variable given as exactly four hex numbers into $0. For example: if B contains 27, then A = hex16 B will print "001B" into the first four positions of $0.

strcmp: This compares the given string with $0. The result is 0 if the strings are the same, -1 when the string is less than $0, and >0 if the string is greater than $0. If one string is shorter than the other, the string is compared against the substring. e.g. "AIRmote 1234" is equal to "AIRmote".

strlen: This returns the length of the string given as a parameter. This command is useful when writing into the file system.

Interrupt Routines

The BASIC program is designed with independent interrupt routines. These are tiggered by events and are not called by program code. They will still be running when the BlueTooth device is disconnected or even when the BASIC Shell is running. For example, PRINTS$0 in an interrupt will overwrite the inputs from the keyboard. When a high speed stream is running, program execution --- even interrupts—are slowed down. The timing, therefore, may be affected by the program requirements.

If you stop the interrupt (i.e. T = nextsns0 within the sensor loop) the program execution will stop. There must be a loop running to which the program will RETURN. Interrupts which are still running when the SHELL is started will over write the inputs at the command line. i.e. @SENSOR will input CR LF at the command line each time it is activated.

Interrupts are preceeded by @ and are Capitalized. i.e. @INIT, @IDLE, @SLAVE, etc. An interrupt is executed only in response to a specific event. The RETURN at the end of an interrupt routine does NOT execute the next line of written code. Instead it releases the interrupt routine. Interrupt routines are specified with the start line number after the interrupt routine specified. Basically, they are subroutines that end with RETURN.

@INIT: This is the routine that runs when the AIRmote starts up. This routine initializes the digital input and output lines. It may also trigger an alarm to blink the LEDs.

@IDLE: After @INIT finishes, and while there is no connection, the idle routine is running.

@SLAVE: As soon as an incoming connection is established, the slave routine starts up. The Bluetooth address from the peer is in $0 as a string.

@MASTER: The master routine is running when an outgoing connection request is successful.

@PIN_CODE: Whenever another Bluetooth device requests a connection, a PIN code must be supplied. The Bluetooth address of the device that requests the PIN code is $0. This BASIC routine returns the PIN code that the other Bluetooth device must use in $0.

@PIO_IRQ: Digital input lines can be configured to create interrupts when the status is changed. (See building function: pioirq.) This routine is started with the status of all digital input lines in $0. They are represented as a string, "P000100" for example.

@INQUIRY: Every time another device is discovered during the inquiry process, the routine starts up. The result of the inquiry is in $0. It starts with the Bluetooth address followed by the name of the remote device. The name starts at $0[13].

@MESSAGE: Whenever an OBEX item is received, the item is stored in the file system. The name of the file is the name provided by the item sender. If the name is longer than twelve characters, the part before the '.' will be shortened to eight characters.

@CONTROL: This routine will be executed when there is a modem request through the SPP interface. If the RTC bit is set in the message, the character '1' is put into the string $0. If it is clear, a '0' will be in the first place of $0.

@SENSOR: When a reading is done, the interrupt routine is called with the result in the string parameter give. It consists of the reading of the corrected analog input in millivolts, the temperature in degrees Celsius, the relative signal strength of the slave SPP connection, and the RSSI of the master SPP connection, if present.

@ALARM: Alarms can be scheduled from the BASIC program using this routine. After a number of seconds are specified in the function, this interrupt routine is executed.

@ERASE: On upload, lines which are removed from the revised code are not overwritten and will remain, mysteriously, in the code loaded into the mote. @ERASE at the beginning of the file will insure that all previous code is removed before the new upload version is loaded.

Program Scheduling

An AIRmote application written in BASIC should not run in an endless loop. It is good practice to use the 3 scheduling mechanism provided.

1. After the AIRmote has started and ran through its @INIT routine, @IDLE will be called. Normally you would open up the incoming serial connection port with the 'slave' command. The 'slave' commands terminates immediately but leaves the port open for a number of seconds. If no connection was established, @IDLE will be called again.
2. Alarms (with the ALARM command) can be scheduled to have the routine @ALARM be called within a number of seconds.
3. The sensor reading scheduler which is started with the 'nextsns' command, can also be used for scheduling application execution. In the @SENSOR routine next sensor readings can be scheduled.

See examples below for application execution scheduling practice.

Interactive BASIC Command-Line Interface

The AIRmotes have a BASIC command-line interface on the slave SPP port, which is active when the UART or master SPP channels are not linked. The little BASIC shell allows the interactive start of BASIC routines and call-building functions. It can also be used to change, add, or delete BASIC program lines.

To log on, open a Bluetooth connection to the SPP port of the AIRmote device. When the connection is established, the @SLAVE routine starts up. In this example, there is a wait of 3 seconds for a '+' and an ENTER to start the interactive shell (otherwise it would link the SPP channel to the UART channel).

When the shell is activated, the system responds with a command prompt: "TAG$."

When the shell is active, it processes the input characters to these rules:

• command is terminated with a CR
• command is < 32 characters
• BACKSPACE deletes the last character
• characters are echoed back
• ctrl-C can be used to stop a running BASIC program

BASIC Commands

The command-line interface has a few BASIC commands:

RUN 40: Starts a BASIC program at that line.

LIST: Prints the BASIC program to the console.

PRINT $1: Prints a single line of BASIC program, line number 1 in this case.

END: Terminates the scheduled ALARM messages and cleans up the stack to remove scheduled functions.

DATE: Prints the current time and date from the real time clock

VERSION: Prints the version number of the AIRmote device.

FILES: Lists the files in the file system with name, size and date.

Editing

A command starts with a line number, followed by a space and the BASIC command line that should be stored at this line number. Any string up to 32 characters long can be typed in. This is used for string variable initialization and BASIC program code. A line number with a single space following it deletes the line.

Interactive Use of Built-in Commands

Built-in commands can be called by typing the function name in lowercase letters. Functions have three different types of parameters, as listed before: no parameter, one variable, or one string. The interface here is more limited than the BASIC execution engine.

For example, the string parameter can be "$4" with one space after the command. No expression evaluation is performed. It can be an immediate string starting after one space without any '"'.

The variable is a BASIC variable. Only one letter in caps is allowed after the space.

Limitations Summary

Line numbers	1-511
Line length	32 characters
FOR nesting	6
GOSUB	8 levels
Expressions	-32768 to 32767, 16-bit
Variables	20, 'A' - 'T'
Parser	expression parser recursive, maximum of 5 levels
File system	maximum of 4 files (in addition to BASIC and config file), maximum of 48-Kbyte file-system space
Bluetooth	maximum of 4 connections at the same time (SPP slave, SPP master, FTP, and OBEX)
BASIC	interpreter, 10 lines per second by default, maximum of about 250 lps

Troubleshooting

Because of the size of the system, not much error checking is performed. It is possible that the BASIC program repeatedly crashes the system and renders the machine unusable. In such a case, use the security overwrite feature in hardware that stops the BASIC engine and keeps only the FTP and OBEX server ports unsecurely open. This is done by opening up the hardware and putting a jumper on the configuration switch. (See hardware manual.)

Expression complexity is very limited. The recursive parser can overrun stack space, which causes the system to reboot.

If a BASIC program stack overflow occurs (e.g. too many interrupts scheduled), the AIRmote will delete the BASIC program from memory and will go into unprogrammed state. The PIN code specified in the "config.txt" file is now the active security information.