Chapter 1 - Introduction

Product Overview

AIRcable OS is a new product line of programmable wireless micro-controllers (W-PLC). These new devices are a fusion of three technologies in one single device:

• BASIC interpreter
• Data logger
• Bluetooth radio

AIRcable Operating System

All our AIRcable OS products are based on the AIRcable operating system. It allows running customer applications in BASIC. They are easily programmable over air through a wireless file transfer (FTP) of a simple text file containing the BASIC code. Our AIRcable OS products are the only embedded Bluetooth products that allow multiple and simultaneous wireless connections. In fact, two serial wireless connections (SPP) can be supported at the same time plus file transfer and message transfer.

Autonomous Operation

A very powerful input and output system implemented within the AIRcable OS allows reading and writing on 3 high speed serial ports: SPP master port, SPP slave port and the UART. Applications run independent of wireless connections and can communicate with sensors and attached devices or user interfaces. The AIRcable Industrial has an additional read/writable file system for data logging and retrieval using standard wireless FTP over OBEX. The interoperability allows even cell phones and PDAs to access the file system wirelessly.

Wireless Sensors

The AIRcable OS products come with a number of intelligent sensor interfaces: real time clock, temperature sensor, high-precision analog to digital sensor, LCD and more. This makes the AIRcable SMD the perfect solution for "smart dust", motes and other wireless sensor products. It is mesh network capable, bootstrap configurable and able to support master and slave operations simultaneously.
The AIRcable OS products are superior wireless sensor interfaces:

• low development and deployment costs
• low hardware cost
• ultra low power of under 50µA with active AIRcable operating system
• extremely long range of up to 28 miles
• interoperability with any PC, laptop, cell phone, PDA, GPS etc.

Summary Benefits

• Wireless micro-controller with powerful wireless functions and high security
• Very easy software development and deployment
• Single processor solution (one chip plus memory), very low hardware costs
• Multiple sensor interfaces, ideal solution for "smart dust" or "motes"
• Compatible with all Bluetooth devices (SPP, FTP, OBEX)
• Full customization available (with or without file system, max BASIC code size, built-in functions, etc.)
• Three connection half-duplex communication ports, two are wireless the other one is an standard DB-9 RS232 compatible UART.

Features

Revolutionary in design and function, the AIRcable OS products unite three cutting-edge technologies — programmable, autonomous mesh nodes (motes), with data loggers and industry-standard Bluetooth® 2.0 compatibility.
Based on our AIRcable operating system, these versatile devices gather data using intelligent sensors, run computations, transfer files, and communicate using Bluetooth technology. These units can be clustered together to create a low-power, highly flexible mesh communications network that can interact with other nodes and with other Bluetooth compatible devices such as PCs, cell phones, laptops, and handhelds.
The communication diagram illustrates how our unit interacts with other devices, with the environment, with applications, and with the user.

BASIC Interpreter

The AIRcable Industrial is an intelligent, autonomous device that can be programmed wirelessly for any application written in standard BASIC - with no code compiler required. You can also access sensors - internal sensors, or those hooked up to the unit's built-in serial port - through your application program.
The AIRcable Industrial's embedded BASIC interpreter includes functions that you can incorporate into your customized programs:

• Bluetooth connectivity (make connections, send files, etc.)
• String operations (a unique feature for a BASIC interpreter)
• Input/output (from all high-speed inputs)
• File system capability

Wireless Data Streaming Ports

Wireless data streaming ports for an uninterrupted flow of information.
Another unique feature is its ability to manage up to four simultaneous connections, including: file upload/download, send/receive messages from other devices, and send/receive streaming data.
Ports include:

• Bluetooth 2.0 Standard (802.11 tolerant)
• 2 wireless data streaming ports using Serial Port Profile (SPP) - one master, one slave
• physical UART port
• FTP connection

Since there are two ports using SPP, both are able to send and receive data. It's much like conducting a conversation with another person. The master, or outgoing port, establishes connections with other devices. The slave, or incoming port, accepts connections. Because the master can connect to another unit, data can be forwarded on to a central location. By using the master, you can connect to another unit through the first unit, which can then connect to another unit, and so forth. This chain of AIRcable Industrial units forms a range extender within the network of units.

Mesh Net

Flexible communication options through mesh net interoperability.
The AIRcable OS is an extremely versatile communication tool. Because it uses the OBEX (OBject EXchange) communications protocol, it can transfer messages such as vCard contact information, vCalendar schedule entries, vNote for Palm/PC, and even applications to other Bluetooth devices such as cell phones, PalmPilots, PCs, or notebooks, or to other AIRcable units. When grouped together or with other Bluetooth compatible devices, AIRcable OS units form a powerful wireless mesh network. For example, vintners can use cell phones to communicate with AIRcable OS units and obtain information about air temperature and soil moisture levels. Retail stores can send coupons to potential customers who pass in front of their store while talking on their cell phones.

File System

A built-in read-and-write file system lets you store, access, and work with data anytime, anywhere.
The device's on-board file system allows you to run BASIC programs and store information gathered by its data-logging function. For example, data streaming in from a sensor connected to the serial port can be loaded directly to its file system. You can access the file system from a PC or your cell phone wirelessly. Best of all, the unit doesn't have to be connected to another device for the file system to work. It performs operations in both connection and autonomous mode. For detailed information on the file system, check out the AIRcable Industrial Programming Manual.

Sensor Interface / Hardware Features

It's durable, rechargeable, and more.
The AIRcable Industrial has a battery-backed real-time clock, a built-in temperature sensor that you can access via the application program, and an antenna port with various indoor and outdoor antenna options for an extended range of up to 28 miles. The devices have a large rechargeable battery and a wide-range charger for wired and solar power panels. The unit can be powered up through the RS232 interface. Enclosed in an aluminum case, the AIRcable Industrial unit is designed to withstand most adverse environmental conditions. Weather-proof versions are also available.
Other hardware features include:

• RS232 interface
• DTR, DSR freely accessible
• High-speed UART
• Automatic hardware

Chapter 2 - Manual Configuration

Programming Over Air

The AIRcable OS device supports wireless file transfer to install application:
Using another Bluetooth compatible device, such as a PC or a PDA, the AIRmote can be detected and will, by default, display the OBEX FTP profile and the OBEX item-exchange profile.

• OBEX FTP file transfer server
• OBEX item exchange server

The OBEX FTP allows users to access the file system and to configure the AIRcable OS device.
Two files are present:

• AIRcable.bas
• config.txt

AIRcable.bas file contains the BASIC program that runs on the AIRcable OS.
While config.txt is the persistent configuration used initially to configure the radio.
In config.txt, further configuration can be disabled. It can be used to allow or prevent upload, download, and any changing of these two files.
The OBEX item-exchange profile is used for communicating with other AIRcable devices using message and for business card exchange. For further details, see Part 3, Message Passing.

Configuration

The file config.txt contains the configuration of the AIRcable OS. This file can be also downloaded from the AIRcable to the PC so that PC users can view the configuration.
It is mainly used to upload from the PC to the AIRcable so that the user can configure the hardware and the Bluetooth radio.
The config.txt file has a specific format. The configuration is a set of lines containing an address and a string of 16-bit hex numbers. The first hex number starts with "@" and the address of the configuration parameter. Then the syntax requires a space, an equal sign, and another space. A number of fixed 4 digit hex values follow.
Example: @0000 = 00c2 0104 0014
These configuration variables are defined as follows:

Example config.txt file

// date
@cccc = 20050828T005500Z
// BT Class of device & version
@0000 = 00c2 0104 0013
// Name of device
@0001 = 0041 0049 0052 0070 0068 006f 006e 0065 0020 0031 0032
// sniff max, min intv, attempt, timeout
@0002 = 0150 0050 0002 0028
// pg scan intv, wind, inq scan intv, wind
@0003 = 0800 0012 1000 0012
// default and max RF output power
@0004 = 0000 0006
// default PIN code
@0005 = 0031 0032 0033 0034
// config security
@0006 = 0000 0000 0000
// baud rate, stop bits, parity
@0007 = 009d 0000 0000
// analog input correction
@0008 = 03e8 03e8

Chapter 3 - Security

PASS KEY or PIN CODE

The AIRcable OS always requires a pass code or PIN the first time a connection is established. PIN codes are required for all incomming and outgoing connections, SPP FTP or OBEX. Authenticaton cannot be disabled.
There are 3 levels of response on PIN code requests depending on the configuration.

• Unconfigured: When the AIRmote is unconfigured (for example, after a firmware upgrade and no config.txt and no AIRcable.bas program has been loaded), the PIN code required to access the AIRcable is fixed at "1234" - very unsecure.
• Configured:After config.txt is uploaded, the PIN code is the PIN code configured in config.txt. If the PIN code length in the config.txt file is zero, it will default to "1234" as well - a bit unsecure if the ObexFTP server is active.
• Programmed: The BASIC program can also respond to PIN code requests. The application knows who is asking for the pass code and can respond accordingly. If a BASIC program responds to a PIN code request, the PIN code used is the result of the PIN_REQ interrupt routine of the BASIC program - the most secure solution, even though ObexFTP server running can make it unsecure as Configured.

PAIRING

A correct PIN code response leads to a successful pairing. The pairing mechanism allows access.
A successful pairing stores a unique link key on both partners. The link key is stored automatically as the pairing information for the two partners. Matching keys then allow access to all wireless channels. This pairing data consists of the Bluetooth address of the partner and its calculated link key. Both have to match before access is granted. If for some reason the partner's link key is removed, the pairing information will no longer match and a new pairing must be established.
For added security the new pairing information will not be updated automatically. Instead of asking for a PIN code again, the connection attempt will fail.
To reestablish pairing, the AIRcable pairing information can be deleted. There are two ways to delete pairing information: delete all stored pairing information or delete individual pairing information. A line containing the keyword @UNPAIR in the BASIC program will erase all pairing information, just as @ERASE deletes the BASIC program.
The first device paired with is the default device. The pairing information of the default device can only be removed by deleting all pairing information. The AIRcable can store the pairing information of 8 other Bluetooth devices. As more pairing is added the oldest pairing information is deleted. Paired devices can be removed in the BASIC program via the built-in function 'unpair bt_addr'. All pairing information is removed with 'unpair 0'. After removing the pairing information a connection attempt will ask for a PIN code again.

ACCESS RESTRICTION

Access to the configuration files AIRcable.bas and config.txt in the file system can be restricted. If bit zero of the first entry in place @0006 is set to one, the two files are invisible. It is not longer possible to download or upload new configuration files.
// config security: no access to config files
@0006 = 0001 0000 0000
Access to user files in the file system is still possible.
Access to the file system service (Obex FTP) can be blocked completely. If bit 2 in the first entry is set to 1, the FTP service will not longer be available. No files, and no configuration can be up or downloaded. The Obex FTP service is not longer available.
// config security: no Obex FTP service
@0006 = 0002 0000 0000
The service to exchange objects such as business cards, vNotes, messages etc. (Obex Object Push) can be disabled as well. The AIRcable can no longer receive messages or business cards from other Bluetooth devices. Set bit 3 to 1.
// config security: no Obex Object Push service
@0006 = 0004 0000 0000
See chapter UNLOCK for information about unlocking the AIRcable.

SECURITY SETTINGS

The security key "@0006" is composed of four 16 bits numbers groups (but only the latest 8 are used in each group), where each of this groups allows you to configure different settings from the AIRcable

FIRST GROUP

0x80 unused
0x40 registers DUN profile when slave is called.
0x20 registers SPP profile when slave is called.
0x10 disable E2FS.
0x08 write protect E2FS.
0x04 disable FTP.
0x02 disable OBEX.
0x01 invisible files in E2FS.

SECOND GROUP

0x01 erase protect BASIC, when stack overflow.
0x00 no stack overflow protection

THIRD AND FOURTH GROUPS

This two groups allows you to take control over the FAT file system processor.

DISCOVERABLE

The AIRcable normally is discoverable. This means that other Bluetooth devices will be able to find the AIRcable. The AIRcable provides its name and available services to anyone who can find it.
Using the slave function the BASIC program can control the discoverablility of the device. All profiles are affected by this mode even though only the slave function controls it. Even after the timeout the inquiry scan is still off. Only a positive value in the slave command will restart inquiry scans.
By setting the number of seconds parameter to a negative number, the AIRmote will become undiscoverable. Even after the timeout the inquiry scan is still off. Only a positive value in the slave command will restart inquiry scans.
After that time, the @IDLE function is called and the slave function can decide to make the AIRcable discoverable again or not.
As long as an external device knows the Bluetooth address a connection can still be made. Whether the AIRcable is discoverable or not, it will still require a successful authentication to grant access.

UNLOCK

It may be necessary for several reasons to unlock the AIRcable once some of the security measures are implemented, or to disable the execution of the BASIC program. Once you lose access to the configuration, there is no way wirelessly to enable configuration again. Certainly a special BASIC program can reenable access again, but that program must already be installed.
The only way to gain access again is to open the housing of the AIRcable Industrial. Inside the AIRcable is a security unlock pin. When this jumper is installed the effect is:

• The AIRcable is discoverable
• Obex FTP and Obex is enabled
• Access to both config files is enabled
• The BASIC interpreter is switched off
• Security PIN code is set to default "1234"
• Device firmware can be updated (dfumode)

This way the configuration and the BASIC program can be updated. Once uploaded the AIRcable has to be switched off, the unlock jumper taken out and the AIRcable then switched on again. If the jumper stays in during reboot, the configuration and the BASIC program will be erased.

On the AIRcable SMD the unlock pin is called SEC or security overwrite.

Chapter 4 - Uploading Code to the AIRcable OS

Using Windows© with Widcomm©

1. Start Bluetooth with "Explore my Bluetooth Places" by clicking on the Bluetooth B icon on your desktop.
2. Click on "Search for devices in range".
3. Find the "AIRcable 12345" and double click on it. (or whatever your serial number is)

1. You see the services the AIRcable Industrial provides. Double click on the OBEX FTP to see the files.

1. It will ask for a PIN code. It is "1234" by default. You must be able to see files using the Bluetooth OBEX file transfer on the AIRcable Industrial.

#Drag and drop the upgrade AIRcable.bas program onto the file. The file name must be AIRcable.bas. Do not rename. Click OK to overwrite the existing program.

The download will stop for a few seconds after 53 bytes. This is normal if the BASIC program contains the instruction "@ERASE". The BASIC memory will be erased before the application download. Download speed is about 200 bytes/s.

Using Windows© with BlueSoleil©

1. Start Bluetooth with "Bluetooth" by clicking on the Bluetooth B icon on your desktop.
2. Click with the right button over the orange big spot in the middle of the screen and then choose general search.
3. Find the "AIRcable 12345" and double click on it. (or whatever your serial number is)

1. You see the services the AIRcable Industrial provides. Click on the OBEX FTP
   

   to see the files.

2. It will ask for a PIN code. It is "1234" by default. You must be able to see files using the Bluetooth OBEX file transfer on the AIRcable Industrial.
3. Drag and drop the upgrade AIRcable.bas program onto the file. The file name must be AIRcable.bas. Do not rename. Click OK to overwrite the existing program.

The download will stop for a few seconds after 53 bytes. This is normal if the BASIC program contains the instruction "@ERASE". The BASIC memory will be erased before the application download. Download speed is about 200 bytes/s

Instructions for Linux and Mac OS comming soon

Chapter 5 - BASIC Language

Variables

The available variables include:

• Integer
• String
• String Index

Integer Variables

Integer Variables are indicated by single capital letters A through Y. Twenty-five variables (A=1, B=2, … Y=25) can be used. The variable named Z is reserved for specialized debugging, and is described later. Variables are not initialized when a program starts. They are initialized when the AIRcable OS reboots. Integer variables are 16-bit signed numbers with a range of -32768 to 32767.

String Variables

String variables are indicated by $ and a number, such as "$5". These string variables are actually the BASIC command lines, meaning that "$10" is the 10th line of the BASIC program. String variables are persistent. All changes to the string variables are written back to the memory into the BASIC program itself. This way an application can have initialized strings stored in BASIC lines.
It is also possible to write a BASIC program that can change itself dynamically, such as download programs or self-configuration programs.
String variables range from $0 to $1023 (or $2047)
$0 is a special variable. It is volatile and not stored permanently. $0 is used for delivering results to and from built-in functions and interrupt routines. For example, writing to a file in the file system will write the content of $0 into the specified file.
$0 variables are longer strings. In this version, $0 has a length of 80 characters. See the use of the PRINTV functions to create longer strings.
An immediate string is put in quotation marks, such as "hello", as a value to initialize a string variable. Immediate strings have a limit of 31 characters.

String Index Variables

Strings can be indexed by using square brackets. For example, $0[0] indicates the first character of the string "$0". String index variables are treated as integer variables with a range of 0 to 255. To write characters to a string index variable, use the decimal representation of the ASCII code. For example, to write an "A" in the first position, use its decimal representation, 65:
$0[0] = 65
Write "A" in the first character of the string.
Expressions
The AIRcable's central execution engine is programmed in an embedded and enhanced BASIC language. The program can be uploaded and downloaded via OBEX FTP over air.
The BASIC program contains BASIC lines. Each BASIC line starts with a line number from 1 to 1023 (or 2047, depending on the configuration) followed by a single space. No spaces are allowed before the line number. A BASIC line can be up to 31 characters in length -including line number, spaces, commands and all punctuation. Except for line 0 which is special and non transient that can take up to 80 chars. Each BASIC line contains one BASIC statement.

Expressions

The AIRcable's central execution engine is programmed in an embedded and enhanced BASIC language. The program can be uploaded and downloaded via OBEX FTP over air.
The BASIC program contains BASIC lines. Each BASIC line starts with a line number from 1 to 1023 (or 2047, depending on the configuration) followed by a single space. No spaces are allowed before the line number. A BASIC line can be up to 31 characters in length -including line number, spaces, commands and all punctuation. Except for line 0 which is special and non transient that can take up to 80 chars. Each BASIC line contains one BASIC statement.
The embedded BASIC language has the following elements:

• Variables
• Expressions
• Statements
• Built-in Functions
• Interrupt Routines

The expression parser in the BASIC interpreter is recursive. Be careful when using complex expressions. Stack space is very limited. The following expressions are evaluated in the ranking below. "expr" is used to indicate an expression.

• number range: 0 - 32768 (or 32767 when using unary minus)
• variables: A-Y
• string index variables: $expr[expr]
• unary minus (negative values): -expr
• brackets: [expr]
• parentheses: (expr)
• multiplication, division: expr * expr or expr / expr
• addition, subtraction: expr + expr or expr - expr

Boolean Expressions

Note: Integer variables can be used for Boolean expressions as well. A zero is treated as false; a non-zero value is true.

Note: string variables cannot be used in expressions. Instead, string index variables should be used at this time. String variables cannot be compared using this mechanism. There are built-in functions available to do that (e.g., strcmp).

• Included since OS version 30.

Statements

BASIC program statements must start with a line number following a space. Line numbers go from 1 to 1023 (or 2047).
The execution is faster when the line numbers are adjacent, with no empty lines in between. The BASIC interpreter executes lines with a default duty cycle of 10 lines per second or actually a delay of 100ms between the lines. This gives the other parts of the system CPU time, such as the Bluetooth baseband functions or the sensor-read functions.
If a statement ends with a ';' the execution of the next line continues without the delay. This way, a speed of about 200 lines per second can be reached, but no other functions (such as Bluetooth operations) can be executed at that time.
All statements are indicated by capital letters only.

Delay

The wait statement increases the default wait time of 100ms to the number of seconds evaluated from the expression as an argument:
WAIT expr
In this case expr has to be an integer value, or WAIT will return immediately.
The wait time may not be accurate. It is possible that a WAIT is interrupted and that execution will commence earlier. To write applications with a time-controlled repeated execution, you can use either the sensor-reading interrupt routine or the alarm interrupt routine and configure the time between readings (see part 3).

Assignments

The substring assignment will copy the string from the position given with the substring argument into the assigned string.

Control Statements

For-loops are indicated in this syntax. Six loops can be nested. The variable controlling the number of iterations must be an integer variable between A and F.
FOR var=expr TO expr
NEXT var

Subroutines

Subroutines are called by the start line number. To return from a subroutine, use RETURN.
GOSUB expr
To jump to another line number, use GOTO.
GOTO expr

Execution Control

IF expr THEN expr
If the first expression evaluates to non-zero, the execution continues at the line number that is the result of the second expression. Otherwise the execution continues on the next line number.
If you need to make a IF - THEUse GOTO to complete this part.

Output

Output can write on 4 different channels:
UART serial port, 'U'
SPP incoming slave serial link, 'S'
Second SPP outgoing master serial link, 'M'
Virtual string output, 'V', which will write into the string $0

Examples on how to send data to the UART

Input and Timeout

Data input can be in two formats from any of three channels:

1. A number terminated with CR (Carriage Return) and
2. A string terminated with CR. For the UART channel, a defined number of bytes can be input as well.

Note: Input into a variable reads a number of digits from the input channel until a CR (Carriage Return) terminates the input. An input into a string variable reads in a string from the channel until a CR (Carriage Return) terminates the input or until the number of characters typed in reaches 32 characters. If $0 is used as the string variable, the limit is 80 bytes.

The UART command reads a certain number of characters from the UART channel into the global string $0. The variable given to the UART command contains the number of characters. This command will not echo or process any input on termination. The UART command puts the number of bytes read back into the variable given as the parameter. You can read as much as 80 chars which each call to UART.

Note: * Since version OS version 30 two new commands had been added to the OS, those are GETU, GETS. GETU is exactly like UART while GETS is like UART for the Slave Port. GETM will be available soon.

By default only INPUTS will process input characters. It will echo incoming bytes and will honor back space to delete the previously typed character. But each channel can be configured to change default behaviour by using STTYU STTYS or STTYM.
By default the various INPUT commands will wait indefinitely until the terminating condition is reached. During this time, no interrupt routines are processed. You should make sure that interrupts such as ALARM, inquiry results and PIN code responds should not happen while you wait for input from the user.
Before calling an INPUT (or UART) command, a TIMEOUT can be scheduled. The TIMEOUT (for each of the three channels separately) takes as an argument an expression. This is the number of seconds before the following INPUT command will terminate

Example

10 PRINTS "type 0 to terminate"
20 TIMEOUTS 10
30 INTPUTS A
40 IF A <> 0 THEN 10
50 END

Input/Output configuration

The values for STTY are:
<COMING SOON>

Capture Input

The CAPTURE statement is a way to log data from the UART to the file system directly. This command is available on AIRcable OS with file system. The "expr" parameter specifies the number of bytes to be logged. A file has to be open for this function to work. CAPTURE does not close the file.
This example logs 100 bytes from the UART into a file with a 60-second timeout.

100 A = open "log.txt"
101 B = 100
102 TIMEOUTU 60
102 CAPTURE B
105 PRINTS "done, size "
106 C = size
107 PRINTS C
108 A = close

Comments

A line beginning with REM is treated as a comment and not executed. The line is indeed stored in the BASIC program occupying program space. A possible practice is to start the line number with 0 to have the line not stored in memory but still have comments in the original BASIC file.
0 REM this is a test

Chapter 6 - Built-in Functions and Interrupt Routines

Types of Instruction

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:
A = atoi "1234"
A = atoi $0
A = atoi $0[5]
The string index parameter is a substring parameter to the function.
Each function has a particular parameter.

List of built-in Functions

General-purpose Input and Output Functions

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.

Bluetooth Functions

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

0 REM wait until ftp/msg successful
420 E = status
421 IF E < 1000 THEN 429
422 WAIT 5
423 GOTO 420

BEGIN:VCARD
VERSION:3.0
N:Smith;Bill
ORG:Wireless Cables Inc.
TEL;PREF;WORK;VOICE: 408 850 1884
END:VCARD

String Functions

Theories of Operation

On the AIRcable Industrial (and other AIRcable OS based devices) a BASIC program controls the Bluetooth baseband processor. Since all operations (Bluetooth, BASIC, timer, etc.) are running on the same processor the device is implemented as a multi tasking system where several tasks perform operations concurrently. The BASIC program controls the multi-tasking system underneath it.

Routines - Interrupts

The BASIC program is organized in routines. Each routine is a section in the BASIC program that starts with @ROUTINE and ends with RETURN. These routines are like interrupt routines in an operating system. The BASIC interpreter knows twelve of these routines:

• @INIT
• @IDLE
• @SLAVE
• @ALARM
• @SENSOR
• @PIO_IRQ
• @MASTER
• @PIN_CODE
• @CONTROL
• @FTP
• @MESSAGE
• @INQUIRY
• @UART

The important programming principle is to keep the routines short. Routines should not occupy the processor for very long and then should end quickly. This allows the Bluetooth baseband processor to execute other tasks that are important in the functioning of the entire system. Routines that do not end (even with WAIT) will block the system.
These routines are scheduled for execution either by the system automatically, by other parts of the program, by external hardware, or by Bluetooth events. Some routines interrupt the execution of other routines because they have a higher priority. For example, the @PIN_CODE routine has the highest priority and will interrupt any other routine. Otherwise, routines are scheduled to run after the current routine has finished.
The BASIC interpreter is still running even when the Bluetooth device is connected or even when the BASIC Shell is running.
When data is streaming through the data ports (linked SPP and UART), the BASIC program execution is slowed down. The timing may be affected by the program status.
Routines are preceeded by @ and are Capitalized (for example, @INIT, @IDLE, @SLAVE, etc.). The line number of the start of that routine must follow the declaration.
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. Basically, they are subroutines that end with RETURN.

@INIT 30
30 A=pioout 3
31 RETURN

Interrupt List

The following two special commands do not require line numbers. They can be put at the first line of the BASIC program.

Running the Application using the Scheduler
The AIRcable Industrial knows 5 program-controlled, scheduled routines.

• @INIT
• @IDLE, @SLAVE
• @MASTER
• @ALARM
• @SENSOR
• And 5 hardware or event scheduled routines.
• @PIN_CODE
• @PIO_IRQ
• @CONTROL
• @MESSAGE
• @INQUIRY
• @UART

After the AIRmote has started and run through its @INIT routine, @IDLE will be called.
Normally you would open up the incoming serial connection port with the 'slave' command. The 'slave' command terminates immediately but leaves the port open for a number of seconds. If no connection was established, @IDLE will be called again. @IDLE is also called when a slave connection closes.

1. Alarms (with the ALARM command) can be scheduled to have the routine @ALARM called within a number of seconds.
2. The sensor reading scheduler which is started with the 'nextsns' command, can also be used for scheduling application execution. In the @SENSOR routine the next sensor readings can be scheduled.

See examples below for application execution scheduling practice.
The following interrupt routines interrupt the BASIC program execution: pair request, inquiry result , message and alarm. All other routines are scheduled for execution after all other scheduled tasks are completed.

The Interactive BASIC Shell

The AIRcable OS devices have a BASIC command-line interface on the slave SPP port. The 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, it is also very usefull for debugging as you can check the code inside a routine with out the respective interrupt.
To log on, open a Bluetooth connection to the SPP port of the AIRcable 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$."

@SLAVE 300
0 REM 3 seconds timeout for the next INPUT
300 PRINTS "type + for shell: "
301 TIMEOUTS 3
302 INPUTS $0
303 IF $0[0] = 43 THEN 306
304 PRINTS "connected"
305 C=link 1
306 A = shell
307 RETURN

When the shell is active, it processes the input characters according 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 started with RUN

SHELL 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.
• PRINT A: Prints the content of variable A
• 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 using the Shell

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. No variable assignment is possible like the use of build-in function in the BASIC code. Functions have three different types of parameters, as listed be fore: 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

Troubleshooting

Due to system size little error checking is performed. In case of a system crash that leaves the device inoperable, use the security overwrite feature in hardware that stops the BASIC engine and keeps only the FTP and OBEX server ports unsecurely open.
Expression complexity is limited. The recursive parser can overrun stack space, which causes the system to reboot.
If a BASIC program stack overflow occurs (for example, too many interrupts scheduled), the AIRcable OS will delete the BASIC program from memory and will go into an unprogrammed state. The PIN code specified in the "config.txt" file is now the active security information.
The special BASIC variable Z can be used for debugging the BASIC code. If Z = 1 the lines the BASIC interpreter executes are printed on the UART. If Z = 2, it prints to the slave port, if Z = 3 it prints to the master SPP port.

This is very helpful to understand what's going on in a system where external events trigger the execution of the BASIC code.

Chapter 7 - Examples - Slave Program, An Annotated Example

Description of the Example

The standard slave program allows other Bluetooth devices such as cell phones, Palmpilots, PDAs, laptops, and PCs to connect to the Bluetooth serial profile of the AIRcable Industrial. To program the AIRcable Industrial with this new program see Programming AIRcable OS.

Operation Principle

When we end this example you will know how to:

• Open the incoming SPP port to allow other Bluetooth devices to connect
• Allow the user to start a shell for manual commands if required
• Configure the UART for 9600 baud
• Link the wireless SPP port to the UART for streaming data

Code Explanations

This simple slave program demonstrates some of the routines and how to program the AIRcable Industrial. We will first explain you each part of the code, and then will show it as hole so you can see it and try it. We had divided the code in 3 parts, and each one is controlled by a different interrupt.
First part is device intialization, as any embeded solution when the device turns on there are other devices that needs to be initializated, in this simple example we will turn on a LED and intializate the RS232 port, but you can do more complex tasks like for example initializating a Display, a GPS device, or what ever you have connected to the device.
Second part is slave channel manipulation this part will open the slave channel and blink a LED to show that the code is running.
The third and final part is slave connection managing this part of the code will accept all the incoming connections, let the user choose between the Shell or RS232 connection, and will turn on both leds.
There are other routines that we handle on this code, which are not exclusive necessary for an slave connection, but we include them to show how the real code should look like.

Device Intialization

The slave program starts with @ERASE. This is a command to the BASIC loader in the AIRcable when a new program is transmitted via wireless FTP. It will cause the AIRcable to erase its BASIC memory completely. The first routine is @INIT, it runs only once when the system is booted or a new BASIC program has been uploaded. In the following example the green LED is first switched on to indicate that the AIRcable boots. The lines 12 to 19 configure the power to the RS232 level shifter and schedule a hardware interrupt on PIO4, this is DSR input on the RS232 connector.

@ERASE
@INIT 10
0 REM LED output and on
10 A=pioout 2
11 A=pioset 2
0 REM RS232_off set
12 A=pioout 5
13 A=pioset 5
0 REM RS232_on set
14 A=pioout 3
15 A=pioset 3
0 REM DTR output clear
16 A=pioout 6
17 A=pioclr 6
0 REM DSR input
18 A=pioin 4
0 REM set DSR to IRQ so that PIO_IRQ is called
19 A=pioirq "P00010000000"
20 RETURN

Slave Channel Manipulation

This part of the code will open the slave channel to accept incoming connections, and will put the device in discoverable mode. The interrupt we are going to use is @IDLE as it is called when ever there is no bluetooth activity, that means whenever the slave channels closes this can be due to slave connection timeout or lost of a slave connection. This routine will also be the first one to be called as soon as @INIT ends.
The BASIC program opens up the incoming serial slave port (SPP) for a number of seconds (A = slave 5) and then exits immediately. The serial slave port (SPP) stays open for other Bluetooth devices to make connections. If a negative value is being used (for example, A = slave -5) the AIRcable Industrial will not be discoverable during this time, and until slave is called again with a possitive value, in this case other Bluetooth devices must know the address to be able to make connections.

@IDLE 30
0 REM disconnect RS232
30 B = unlink 1
31 B = slave 5
0 REM blink LED
32 B = pioset 2;
33 B = pioclr 2
34 RETURN

Slave connection managing

When a connection to the slave port is successful, meaning another Bluetooth device has initiated a connection to the AIRcable, the @SLAVE routine starts up. The BASIC program can find out who is connecting using the built-in function getconn (for example, A = getconn $0). For a simple slave application the program would link the wireless SPP port to the UART. This routine allows also user to start an interactive session with the built-in shell. When a '+' and an enter is typed in immediately after the connection has been established the AIRcable Industrial starts with a BASIC interpreter shell. It is possible to change lines of the BASIC program, start or stop routines, print variables and call built-in functions.

@SLAVE 400
0 REM 5 seconds timeout to start shell with '+' and enter
400 TIMEOUTS 5
401 INPUTS $0
402 IF $0[0] = 43 THEN 407
403 B = pioset 2
0 REM set baud rate to 9600
404 C = baud 96
0 REM connect RS232
405 C = link 1
406 RETURN
407 A = shell
408 RETURN

Extras

A successful connection requires that the two partners are paired. PIN code is exchanged and then a unique link key is stored on both ends to indicate a successful pairing. The pairing information is stored persistently for future connections that will no longer need a PIN code. Pairing information can be erased, when more than 8 peers are stored, or manually with the unpair function (single peers), or the @UNPAIR command (all peers) at the beginning of a BASIC program upload.
The PIN code that is used for all connections (slave, master, ftp and obex) is configured here in the BASIC program. This way, the application has more control over security. When @PIN_CODE is called, the Bluetooth address of the device requesting connection is available in the $0 string variable. This variable is being used for the PIN code response as well.

@PIN_CODE 440
0 REM fixed PIN code
440 $0="1234"
441 RETURN

The last 2 routines @PIO_IRQ and @CONTROL deal with the handshake lines on the RS232 ports. If the DSR input on the DB9 connection changes, @PIO_IRQ is called. This was already initialized with the earlier instruction "A=pioirq "P00010000000" in the @INIT routine.

The function modemctl transmits a message through an established SPP connection to the other end. Receiving this message will schedule the @CONTROL routine to be executed. In this example we set or reset the DTR pin of our RS232 connector.

@PIO_IRQ 490
0 REM local request for DSR
490 IF $0[4] = 48 THEN 483
0 REM modem control to other side
491 A = modemctl 1
492 RETURN
493 A = modemctl 0
494 RETURN

@CONTROL 495
0 REM remote request for DTR
495 IF $0[0] = 49 THEN 498
496 A=pioset 6
497 RETURN
498 A=pioclr 6
499 RETURN

Entire Program

@ERASE
@INIT 10
0 REM LED output and on
10 A=pioout 2
11 A=pioset 2
0 REM RS232_off set
12 A=pioout 5
13 A=pioset 5
0 REM RS232_on set
14 A=pioout 3
15 A=pioset 3
0 REM DTR output clear
16 A=pioout 6
17 A=pioclr 6
0 REM DSR input
18 A=pioin 4
0 REM set DSR to IRQ so that PIO_IRQ is called
19 A=pioirq "P00010000000"
20 RETURN

31 B = slave 5
0 REM blink LED
32 B = pioset 2;
33 B = pioclr 2
34 RETURN

@SLAVE 400
0 REM 5 seconds timeout to start shell with '+' and enter
400 TIMEOUTS 5
401 INPUTS $0
402 IF $0[0] = 43 THEN 407
403 B = pioset 2
0 REM set baud rate to 9600
404 C = baud 96
0 REM connect RS232
405 C = link 1
406 RETURN
407 A = shell
408 RETURN

@PIN_CODE 440
0 REM fixed PIN code
440 $0="1234"
441 RETURN
@PIO_IRQ 480
0 REM when DSR on the RS232 changes
480 IF $0[4]=48 THEN 483
0 REM modem control to other side
481 A=modemctl 1
482 RETURN
483 A=modemctl 0
484 RETURN

@CONTROL 495
0 REM remote request for DTR pin on the RS232
495 IF $0[0] = 49 THEN 498
496 A=pioset 6
497 RETURN
498 A=pioclr 6
499 RETURN
@IDLE 30
0 REM disconnect RS232
30 B = unlink 1

Chapter 8 - Examples - Master Program, An Annotated Example

Introduction

Description of the Example:

This section of the programming handbook describes the implementation of a serial port profile master program for the AIRcable Industrial. It serves as a good example of how to debug wirelessly.

Operation Principle

When we end this example you will know how to:

• Discover other Bluetooth devices in range
• Filter out one peer with a particular, friendly name
• Connect to the remote device on the serial port (SPP)
• Configure the UART for 9600 baud and odd parity
• Link the wireless SPP port to the UART for streaming data

Debugging

While the AIRcable Industrial is finding other Bluetooth devices and streaming data, it is still accepting slave connections. We use the second wireless serial port (the slave SPP) for debugging. Make a SPP connection to the AIRcable and run a terminal emulator (such as Hyperterminal) on the connected slave SPP port. The BASIC interpreter will write every BASIC line it executes and debug any strings the BASIC program writes to the slave port. This is independent of the data communication between the peer Bluetooth device connected through the master port and the UART.

Theories of Operation

On the AIRcable Industrial (and other AIRcable OS based devices) a BASIC program controls the Bluetooth baseband processor. Since all operations (Bluetooth, BASIC, timer etc) are running on the same processor, the device is implemented as a multi-tasking system where several tasks perform operations concurrently. The BASIC program controls the multi-tasking system underneath it.
The BASIC program is organized in routines. Each routine is a section in the BASIC program that starts with @ROUTINE and ends with RETURN. These routines are like interrupt routines in an operating system. The BASIC interpreter knows 12 of these routines:

1. # @INIT
2. # @IDLE
3. # @SLAVE
4. # @ALARM
5. # @SENSOR
6. # @PIO_IRQ
7. # @MASTER
8. # @PIN_CODE
9. # @CONTROL
10. # @MESSAGE
11. # @INQUIRY
12. # @UART

The important programming principle is to keep the routines short. This means that routines should not occupy the processor for very long and then it should end quickly. This allows the Bluetooth baseband processor to execute other tasks that are important for the functionality of the whole system. Routines that don't end (even with WAIT) will block the system.
These routines are scheduled for execution either by the system automatically, or by other parts of the program or by external hardware or Bluetooth events. Some of the routines interrupt the execution of other routines because they have higher priority. For example, the @PIN_CODE routine has the highest priority and will interrupt any other routine. Otherwise routines are scheduled to run after the current routine is finished.

Code Explanations

The implementation of the master program will serve as an example of the various routines available. The master program starts with @ERASE. This is a command to the BASIC loader in the AIRcable when a new program is transmitted via wireless FTP. It will cause the AIRcable to erase its BASIC memory completely. As the other example (slave code), we had divided the code in several parts so it is more easy to understand.

Device Initialization

The first routine is @INIT. It runs only once when the system is booted or a new BASIC program has been uploaded. In this example the green LED is first switched on to indicate that the AIRcable boots. The lines 7 to 19 configure the power to the RS232 level shifter and schedule a hardware interrupt on PIO4. This is DSR input on the RS232 connector.
The PIN code that is used for connections (slave, master and ftp) is configured here in the BASIC program. This gives the application more control over security. Communication is only with devices with a friendly name starting with "PUMP" the string variables are initialized here as well. Debugging is switched on using the special variable Z. A value of 2 means to send debugging to the slave port.
The state engine is initialized and any pending wireless links are disconnected. This is helpful when changing programs frequently without rebooting the AIRcable. Slave ports are not disconnected so that the initialization execution on the slave port can be determined when a new version is uploaded.

@ERASE
@INIT 10
0 REM LED output and on
10 A=pioout 2
11 A=pioset 2
0 REM RS232_off set
12 A=pioout 5
13 A=pioset 5
0 REM RS232_on set
14 A=pioout 3
15 A=pioset 3
0 REM DTR output clear
16 A=pioout 6
17 A=pioclr 6
0 REM DSR input
18 A=pioin 4
0 REM set DSR to IRQ so that PIO_IRQ is called
19 A=pioirq "P00010000000"
0 REM PIN code
20 $1 = "1234"
0 REM connect to devices starting with
21 $2 = "PUMP"
0 REM connection state variable X
0 REM 1=found, 2=connecting, 3=connected, 4=slave restarted
22 X = 0
23 IF $4[0] = 0 THEN 26
0 REM we have a saved connection address, try first
24 $3 = $4
25 X = 1
0 REM switch on debug to the slave port
26 Z = 2
0 REM 25 A = disconnect 0
27 A = disconnect 1
28 A = unlink 1
29 ALARM 2
30 IF Z <> 2 THEN 32
31 PRINTS $3
32 RETURN

Running the Application using the Scheduler

The AIRcable Industrial knows 5 program-controlled, scheduled routines:

• @INIT
• @IDLE, @SLAVE
• @MASTER
• @ALARM
• @SENSOR
• And 6 hardware or event scheduled routines:
• @PIN_CODE
• @PIO_IRQ
• @CONTROL
• @MESSAGE
• @INQUIRY
• @UART

Slave Connections

@IDLE is called whenever a slave connection is not available or when a slave connection closed. This routine starts right after @INIT. Normally the BASIC program would open up the incoming serial slave port (SPP) for a number of seconds and then exit. It will be called again when the time is up and no connection was established. At this time the BASIC program will again open up the slave port for incoming connections to SPP.
When a connection to the slave port is successful, meaning another Bluetooth device has initiated a connection to the AIRcable, the @SLAVE routine starts up. The BASIC program can find out who is connecting using the built-in function getconn.
A successful connection requires that the two partners are paired. PIN code is exchanged and then a unique link key is stored on both ends to indicate a successful pairing. The pairing information is stored persistently for future connections that will no longer need a PIN code. Pairing information can be erased either when more than 8 peers are stored or manually with the unpair function (single peers) or the @UNPAIR command (all peers) at the beginning of a BASIC program upload.
In a simple slave application the program would link the wireless SPP port to the UART. Fundamentally, this example does the same.

@IDLE 40
0 REM slave port stopped
40 Y = 0
0 REM give the processor time to
0 REM finish a pending master connection
0 REM this is in state 1, 2 and 3
41 IF X = 1 THEN 46;
42 IF X = 2 THEN 46;
43 IF X = 3 THEN 46;
REM in state 0 and 4: allow slave for 5 seconds
44 A = slave 5
0 REM slave port open now
45 Y = 1
46 RETURN

@SLAVE 90
0 REM slave connection to shell
90 A = pioset 2
91 A = shell
92 RETURN

@PIN_CODE 488
488 $0 = $1
489 RETURN

Master Connections

In more complex master examples the program allows master and slave connections at the same time. Basically there are three ways to achive this: a state machine allowing the Bluetooth baseband processor to do master connections without conflicting with the slave connections, scheduling @ALARM interrupt and checking for Bluetooth status with A=status, and the final is a combination of the two you do have a state machine, but you still check the Bluetooth activity to be more secure.
In this simple example we will use an state machine, but if you want to see a combination of both we strongly recommend that you read the developers manual on command line implementation - COMMING SOON.
The states are as follows, with the variable X used to keep state.
0. State is initial state.
1. We have found a peer that matches the criteria
2. We are in process to connect as master to the peer
3. We have successfully connected to the peer
4. We are connected as master
Looking at the @IDLE routine, slave connections are only allowed when inquiries are still going on, or when a master connection has been established. When the slave connection mechanism is scheduled while a master connection is being established it causes conflicts. @IDLE will return in those cases and will have to be rescheduled when a certain state is reached.
The @MASTER routine is called whenever a master connection is successful. This is the second program-controlled, scheduled routine. The routine is simple. It configures the UART with 9600 baud and odd parity and links the SPP master port to the UART. We also store the address of the peer in $4(if connection is lost, reconnect to this address first before starting the inquiry process). Since a longer master connection timeout has been scheduled (20sec), a quicker alarm should be rescheduled.

@MASTER 100
0 REM save the address we conn
100 $4 = $3
0 REM debug message
102 IF Z = 0 THEN 105
103 PRINTS "master connected\n"
104 PRINTS $3
0 REM LED on
105 A = pioset 2
0 REM config 9600 baud, odd parity
106 A = uartcfg 35
0 REM link MASTER and UART
107 A = link 2
0 REM set state master connected
108 X = 3
0 REM reschedule ALARM quicker
109 ALARM 1
110 RETURN

Use the ALARM scheduler as the main control mechanism to control the whole application. All execution is initiated by @ALARM, depending on the state described above.
Because inquiries are expensive in processing time and in power consumption, wait when inquiries are occurring. Leave the processor as much time as possible to do inquiries.
The results are scheduled by calls to @INQUIRY. Inquiry routines are sensitive to interrupts by other inquiry results. To prevent interruption a semicolon can be placed after a BASIC instruction. Normally the BASIC interpreter executes one line of BASIC program and then allows other parts of the system to execute before it goes to the next line. At the moment it schedules the execution of each line for every 100ms. With the placement of the semicolon this wait does not happen, the BASIC interpreter executes the next line immediately without going back to the scheduler. Use the semicolon carefully.
@INQUIRY looks at the result and compares the name of the discovered Bluetooth device with the string in $2. If the name starts with that, it sets the state to "found", cancels any further inquiries, and prints some debug. (See a chapter at the end about debugging.)

0 REM process inquiry results
0 REM routine must have ';'
@INQUIRY 200
0 REM found peer, ignore other results
200 IF X >= 1 THEN 224;
201 $3 = $0;
202 $0 = $3[13];
0 REM only devices starting with this
203 B = strcmp $2;
204 IF B <> 0 THEN 220;

0 REM found, no more search
205 A = cancel;
206 X = 1;

0 REM debug
208 IF Z = 0 THEN 212;
209 S = status;
210 IF S = 1 THEN 213;
211 IF S = 10001 THEN 213;
212 RETURN

213 PRINTS "connecting "
214 PRINTS $0
215 PRINTS "\r\n"
216 RETURN

0 REM keep ';'
220 IF Z = 0 THEN 224;
221 S = status;
222 IF S = 1 THEN 225;
223 IF S = 10001 THEN 225;
224 RETURN

225 PRINTS "not "
226 PRINTS $0;
227 PRINTS "\r\n"
228 RETURN

As for @ALARM, a standard state engine switch is at the beginning and fans out from there to the different procedures depending on the state. Note that in every state we reschedule another ALARM within a few seconds to keep the system running. Switching state forward is mostly done in these procedures.

0 REM use ALARM routine to make master connections
@ALARM 400
0 REM wait until inquiry stops
400 S = status;
401 IF S < 10000 THEN 410;
0 REM still inquiring, schedule next ALARM
402 ALARM 2;
0 REM blink LED
403 B = pioset 2;
404 B = pioclr 2;
405 RETURN

0 REM state machine
410 IF X = 0 THEN 430;
411 IF X = 1 THEN 440;
412 IF X = 2 THEN 450;
413 IF X = 3 THEN 460;
415 IF X = 4 THEN 470;
0 REM should never happen
416 X = 0
417 GOTO 430

0 REM state 0: init, do inquiries
430 ALARM 6
0 REM blink LED
431 B = pioset 2;
432 B = pioclr 2
433 A = inquiry 11
434 RETURN

0 REM state 1: found
440 $0 = $3
441 IF Z <> 2 THEN 443
442 PRINTS $0
443 A = master $0
0 REM set state to "connecting"
444 X = 2
0 REM give it 20 seconds timeout
445 ALARM 20
0 REM blink LED
446 B = pioset 2;
447 B = pioclr 2
448 RETURN

0 REM state 2: timeout connecting, restart slave
450 X = 0
454 S = status
0 REM if we have a slave connection skip
455 IF S = 1 THEN 458
456 A = slave 1
457 Y = 1
0 REM safety, no master connections
458 A = disconnect 1
459 GOTO 410

0 REM state 3: master connected, restart slave
0 REM only if no slave connected
460 S = status
461 IF S = 11 THEN 464
462 A = slave 1
463 Y = 1
464 X = 4
465 ALARM 5
466 RETURN

0 REM state 4: connected, slave restarted
0 REM handle lost master connections
470 IF S < 1000 THEN 472
471 S = S - 1000
472 IF S < 100 THEN 474
473 S = S - 100
474 IF S < 10 THEN 480
0 REM still has master connection, blink reverse
475 ALARM 5
476 B = pioclr 2;
477 B = pioset 2
478 RETURN

0 REM lost master connection, reset state
480 A = unlink 2
481 X = 0
482 IF $4[0] = 0 THEN 485
483 X = 1
484 $3 = $4
485 GOTO 410

Extras

The last 2 routines @PIO_IRQ and @CONTROL deal with the handshake lines on the RS232 ports. If the DSR input on the DB9 connection changes, @PIO_IRQ is called. This was already initialized with the earlier instruction "A=pioirq "P00010000000" in the @INIT routine.
The function modemctl transmits a message through an established SPP connection to the other end. When the message is received it will schedule the @CONTROL routine to be executed. This example sets or resets the DTR pin of our RS232 connector.

@PIO_IRQ 490
0 REM local request for DSR
490 IF $0[4] = 48 THEN 483
0 REM modem control to other side
491 A = modemctl 1
492 RETURN
493 A = modemctl 0
494 RETURN

@CONTROL 495
0 REM remote request for DTR
495 IF $0[0] = 49 THEN 498
496 A=pioset 6
497 RETURN
498 A=pioclr 6
499 RETURN

Debugging

Debugging is much easier since version 24. A special variable Z is used to switch on debugging of the BASIC interpreter. Every line it executes is printed on one of the 3 data channels, UART, SPP-slave, or SPP-master. We use the SPP-slave port to send the BASIC lines executed and additional debugging information.
The debugging code in the program makes sure that data is not sent to a channel that is not connected. The AIRcable will buffer some data when there is no connection, but it will reduce memory and cause unnecessary processing.

Entire Program
Note: This is the entire program, with debugging switched on. To use the program in production without debugging, change line 26 to "Z = 0".

@ERASE

@INIT 10
0 REM LED output and on
10 A=pioout 2
11 A=pioset 2
0 REM RS232_off set
12 A=pioout 5
13 A=pioset 5
0 REM RS232_on set
14 A=pioout 3
15 A=pioset 3
0 REM DTR output clear
16 A=pioout 6
17 A=pioclr 6
0 REM DSR input
18 A=pioin 4
0 REM set DSR to IRQ so that PIO_IRQ is called
19 A=pioirq "P00010000000"
0 REM PIN code
20 $1 = "1234"
0 REM connect to devices starting with
21 $2 = "PUMP"
0 REM connection state variable X
0 REM 1=found, 2=connecting, 3=connected, 4=slave restarted
22 X = 0
23 IF $4[0] = 0 THEN 26
0 REM we have a saved connection address, try first
24 $3 = $4
25 X = 1
0 REM switch on debug
26 Z = 2
0 REM 25 A = disconnect 0
27 A = disconnect 1
28 A = unlink 1
29 ALARM 2
30 IF Z <> 2 THEN 32
31 PRINTS $3
32 RETURN

@IDLE 40
0 REM slave port stopped
40 Y = 0
0 REM give the processor time to
0 REM finish a pending master connection
0 REM this is in state 1, 2 and 3
41 IF X = 1 THEN 46;
42 IF X = 2 THEN 46;
43 IF X = 3 THEN 46;
REM in state 0 and 4: allow slave for 5 seconds
44 A = slave 5
0 REM slave port open now
45 Y = 1
46 RETURN

@SLAVE 90
0 REM slave connection to shell
90 A = pioset 2
91 A = shell
92 RETURN

@MASTER 100
0 REM save the address we conn
100 $4 = $3
0 REM debug message
102 IF Z = 0 THEN 105
103 PRINTS "master connected\n"
104 PRINTS $3
0 REM LED on
105 A = pioset 2
0 REM config 9600 baud, odd parity
106 A = uartcfg 35
0 REM link MASTER and UART
107 A = link 2
0 REM set state master connected
108 X = 3
0 REM reschedule ALARM quicker
109 ALARM 1
110 RETURN

0 REM process inquiry results
0 REM routine must have ';'

@INQUIRY 200
0 REM found peer, ignore other results
200 IF X >= 1 THEN 224;
201 $3 = $0;
202 $0 = $3[13];
0 REM only devices starting with this
203 B = strcmp $2;
204 IF B <> 0 THEN 220;

0 REM found, no more search
205 A = cancel;
206 X = 1;

0 REM debug
208 IF Z = 0 THEN 212;
209 S = status;
210 IF S = 1 THEN 213;
211 IF S = 10001 THEN 213;
212 RETURN

213 PRINTS "connecting "
214 PRINTS $0
215 PRINTS "\r\n"
216 RETURN

0 REM keep ';'
220 IF Z = 0 THEN 224;
221 S = status;
222 IF S = 1 THEN 225;
223 IF S = 10001 THEN 225;
224 RETURN

225 PRINTS "not "
226 PRINTS $0;
227 PRINTS "\r\n"
228 RETURN

0 REM use ALARM routine to make master connections
@ALARM 400
0 REM wait until inquiry stops
400 S = status;
401 IF S < 10000 THEN 410;
0 REM still inquiring, schedule next ALARM
402 ALARM 2;
0 REM blink LED
403 B = pioset 2;
404 B = pioclr 2;
405 RETURN

0 REM state machine
410 IF X = 0 THEN 430;
411 IF X = 1 THEN 440;
412 IF X = 2 THEN 450;
413 IF X = 3 THEN 460;
415 IF X = 4 THEN 470;
0 REM should never happen
416 X = 0
417 GOTO 430

0 REM state 0: init, do inquiries
430 ALARM 6
0 REM blink LED
431 B = pioset 2;
432 B = pioclr 2
433 A = inquiry 11
434 RETURN

0 REM state 1: found
440 $0 = $3
441 IF Z <> 2 THEN 443
442 PRINTS $0
443 A = master $0
0 REM set state to "connecting"
444 X = 2
0 REM give it 20 seconds timeout
445 ALARM 20
0 REM blink LED
446 B = pioset 2;
447 B = pioclr 2
448 RETURN

0 REM state 2: timeout connecting, restart slave
450 X = 0
454 S = status
0 REM if we have a slave connection skip
455 IF S = 1 THEN 458
456 A = slave 1
457 Y = 1
0 REM safety, no master connections
458 A = disconnect 1
459 GOTO 410

0 REM state 3: master connected, restart slave
0 REM only if no slave connected
460 S = status
461 IF S = 11 THEN 464
462 A = slave 1
463 Y = 1
464 X = 4
465 ALARM 5
466 RETURN

0 REM state 4: connected, slave restarted
0 REM handle lost master connections
470 IF S < 1000 THEN 472
471 S = S - 1000
472 IF S < 100 THEN 474
473 S = S - 100
474 IF S < 10 THEN 480
0 REM still has master connection, blink reverse
475 ALARM 5
476 B = pioclr 2;
477 B = pioset 2
478 RETURN

0 REM lost master connection, reset state
480 A = unlink 2
481 X = 0
482 IF $4[0] = 0 THEN 485
483 X = 1
484 $3 = $4
485 GOTO 410

@PIN_CODE 488
488 $0 = $1
489 RETURN

@PIO_IRQ 490
0 REM local request for DSR
490 IF $0[4] = 48 THEN 483
0 REM modem control to other side
491 A = modemctl 1
492 RETURN
493 A = modemctl 0
494 RETURN

@CONTROL 495
0 REM remote request for DTR
495 IF $0[0] = 49 THEN 498
496 A=pioset 6
497 RETURN
498 A=pioclr 6
499 RETURN

Chapter 9 - Writing Interactive Programs

Introduction

Writing interactive programs can be challenging because the BASIC program can block the execution of other parts in the system. For example, the INPUT functions will hold the BASIC program at that line. If an interrupt occurs (sensor alarms, PIN code requests, etc.) the request does not get fulfilled until the INPUT times out or finishes.
The programmer should keep in mind:

• Avoid using endless loops
• Use one of the schedulers to run interactive functions
• Always use TIMEOUT during input

Schedulers

There are 5 different schedulers that can be used to schedule operations:

1. @IDLE, slave
2. @ALARM
3. @SENSOR, nextsns
4. @INQUIRY, inquiry
5. @PIO_IRQ (external trigger)

Example

The slave function opens the Bluetooth SPP port for incoming connections for a specified time. The function itself returns immediately allowing other operations to continue while the system accepts incoming connections. After this time, the @IDLE routine will be started again. The @IDLE must return before that happens. The following example allows the reading of a command from the UART while the system is idle (or accepting incoming connections). Note: timeout expires before slave expires to restart @IDLE.

@IDLE 10
10 A = slave 10
11 TIMEOUTU 8
12 INPUTU $0
13 IF $0[0] <> 0 THEN 20
14 RETURN

0 REM check for 'A' 'B' and 'C'
20 IF $0[0] = 65 THEN 24
21 IF $0[0] = 66 THEN 30
22 IF $0[0] = 67 THEN
23 RETURN

24 PRINTU "> "
0 REM real stop
25 INPUTU A
26 IF A <> 0 THEN ok:
27 RETURN

30 PRINTU "Returning"
32 RETURN

35 PRINTU"ALARM has been
36 PRINTU" scheduled
37 ALARM 5
38 RETURN

The alarm scheduler can be used the same way, as in this example:

@ALARM 50
50 ALARM 6
51 TIMEOUTU 5
52 INPUTU A
53 RETURN

This is the approach we had taken in our Command Line software.

Chapter 10 - Examples - Code Fragments

Introduction

In this last section we will show you some code fragments that you can use as a reference. This fragments will not work out of the box, you will need to make some changes to them in order to use them, but can be used as a reference to see how to do some things.

Wire sensor reading into file system

This example shows the use of the MultiSensor from iButtonLink.com. It logs temperature and humidity into the file system for later download.

0 REM start 1-wire
50 T = pioclr 6
51 T = uarton
52 T = baud 96
53 PRINTU "D";
54 $0[0] = 0
55 TIMEOUTU 2
56 INPUTU $0
0 REM if we have an 'E' (69) end routine
57 IF $0[0] <> 69 THEN 60;
58 PRINTS "EOD\n"
59 RETURN

0 REM timeout
60 IF $0[0] = 0 THEN 62
61 GOTO 65
62 PRINTS "timeout\n"
63 RETURN

0 REM see if we have a "26" (50,54) start
65 IF $0[0] = 50 THEN 69;
66 PRINTS "no "
67 REM PRINTS $0
68 GOTO 54
0 REM read next line from uart
69 IF $0[1] <> 54 THEN 54;
70 PRINTS $0
71 S = append "tmplog.txt"
72 Q = size
0 REM don't overrun file, stop
73 IF Q > 200 THEN 80
0 REM read clock and overwrite first 16
74 S = date $0
0 REM change the null to a space
75 $0[16] = 32
0 REM add newline to the end of the string
76 PRINTV "\n"
77 PRINTS $0
78 R = strlen $0
79 S = write R
80 S = close
81 GOTO 54

Send Sensor Data via OBEX

This example reads binary data from a gas sensor, converts it into a string and sends it via an OBEX vNote to another Bluetooth machine every 10 seconds.

0 REM gas sensor read function

50 T = 17
51 TIMEOUTU 2
52 PRINTU "\x04"
53 UART T
0 REM see if we get a 0xfd
54 IF $0[0] <> 253 THEN 69;
55 $1 = $0
56 REM PRINTS "found\n"
57 $0[0] = 0;
58 FOR I = 0 TO 16;
59 PRINTV $1[I];
60 PRINTV " "
61 NEXT I
62 REM PRINTS $0
64 REM C = message "0013105D4CAC"
65 C = message "000B0D04B695"
66 REM PRINTS "sent\n"
67 REM WAIT 5
68 REM GOTO 50
69 RETURN

@ALARM 400
400 D=status;
401 IF D = 0 THEN 410
402 D=pioget 2;
403 IF D = 0 THEN 407
404 D=pioclr 2
405 ALARM 1
406 RETURN
407 D=pioset 2
408 ALARM 2
409 RETURN
0 REM just blink short
410 D=pioset 2
411 D=pioclr 2
0 REM keep DTR on
412 D=pioclr 6
0 REM read sensor
413 GOSUB 50
0 REM do it again in 5 seconds
414 ALARM 5
415 RETURN

Send Sensor Data via FTP

This is a version of the program that reads the sensor and puts the data in a file, then FTPs the file over to another device.

0 REM sensor reading program
50 T = 17
51 TIMEOUTU 2
52 PRINTU "\x04"
53 UART T
0 REM see if we get a 0xfd
54 IF $0[0] <> 253 THEN 97;
55 $1 = $0
58 S = open "sensor.sns"
0 REM change binaries to string
60 $0[0] = 0
61 FOR I = 0 TO 16
62 PRINTV $1[I];
63 PRINTV " ";
64 NEXT I;
66 R = strlen $0
67 S = write R
68 REM PRINTS $0
69 GOTO 90
90 S = close
91 S = open "sensor.sns"
92 REM $0 = "0013105D4CAC"
93 $0 = "0800170FA7B7"
94 U = ftp "FromSEE.sns"
95 REM WAIT 5
96 REM GOTO 50
97 RETURN

Log System Boot

This initialization routine logs the date into a file when the system boots up.

@INIT 10
0 REM RS232_off set
11 A=pioout 5
12 A=pioset 5
0 REM RS232_on set
14 A=pioout 3
15 A=pioset 3
0 REM DTR output clear
17 A=pioout 6
18 A=pioclr 6
0 REM DSR input
20 A=pioin 4
21 REM set DSR to IRQ
22 A=pioirq "P000100"
0 REM LED output and on
24 A=pioout 2
25 A=pioset 2
0 REM alarm in 5 seconds

0 REM boot log
30 A = append "bootlog.txt"
31 A = size
32 IF A > 1000 THEN 52
33 A = date $0
0 REM add newline to the end of the string
34 PRINTV "\n"
35 A = strlen $0
36 B = write A
37 A = close
0 REM that's it
38 ALARM 5
39 RETURN

52 A = exist "bootlog.bak"
53 IF A = 0 THEN 45
54 A = delete "bootlog.bak"

55 A = rename "bootlog.bak"
56 A = close
0 REM create a new file
57 A = open "bootlog.txt"
58 GOTO 33

Break an Incoming Data Streaming Connection

This example shows how to break an incoming data streaming connection within a certain period of time.

@SLAVE 300
0 REM 5 seconds timeout for the next INPUT
300 PRINTS "type + for shell: "
301 TIMEOUTS 5
302 INPUTS $0
303 IF $0[0] = 43 THEN 312
304 PRINTS "connected for 30s\n"
305 C = date $0
306 PRINTS $0
307 PRINTS "\n"
308 ALARM 30
0 REM stop reading aio
309 C = nextsns 0
310 C = link 1
311 RETURN

312 PRINTS "shell started\n"
313 C = nextsns 10
314 RETURN

@ALARM 400
400 C = unlink 1
401 PRINTS "shell started\n"
402 C = date $0
403 PRINTS $0
404 PRINTS "\n"
405 C = nextsns 10
406 RETURN

Log Serial Data into File System

This example shows the capture capabilities to log UART serial data directly into the file system.

0 REM test program for CAPTURE
250 S = open "log.txt"
251 R = 1000
252 TIMEOUTU 60
252 CAPTURE R
255 PRINTS "done, size "
256 Q = size
257 PRINTS Q
258 PRINTS "\n"
259 S = close
260 END

FTP Test Routine

This test routine sends a file via FTP to another Bluetooth device, such as a PC, laptop or Palmpilot, discovering the other device via an inquiry process, and is named "PALM2".

@INQUIRY 100
0 TEST ftp transfer
100 $1 = $0;
0 REM substring assignment
101 $2 = $1[13];
102 C = cancel
103 C = strcmp "PALM2"
104 IF C = 0 THEN 107
105 PRINTS $2
106 RETURN
107 C = open "vCard.vcf"
108 $0 = $1;
109 C = ftp "fromair.vcf"
110 RETURN

vNote Message

When a (vNote)message is received, the BODY part of the vNote is printed as a message:

@MESSAGE 500
500 PRINTS "msg received "
501 PRINTS $0
502 RETURN
Read from the UART
Read only 10 bytes from the UART
0 REM test UART input
141 PRINTU "type 10"
142 PRINTU "\n"
143 S=10;
144 UART S
145 PRINTU "got "
146 PRINTU $0
147 PRINTU "\n"
148 END