Welcome to the BlueBasic wiki! https://github.com/ozarchie/BlueBasic/wiki

Things to know:

REBOOT [UP]

Reboots the device. Optional parameter UP sets the device in restore mode for firmware upgrade. This is helpful when you want to program a new firmware in the filed with your iPhone. You then can use the BlueBasic-xxx.bin file together with the TI SimpleLink Starter App by emailing yourself the bin file and open it in the TI App.

After uploading a new BASIC program, the device stalls when disconnecting the bluetooth connection. AUTORUN ON doesn't do the trick. In this situation a device reset is the only way out. To avoid this situation (e.g. when upgrading a device deeply buried somewhere) use this sequence:

Upload BASIC program and issue at the the end:

AUTORUN ON
REBOOT   <-- here you need to be quick and disconnect the bluetooth connection

When you have been fast enough the device executes AUTORUN ON and everything runs normal. If you are too slow, the device will not start to work until you issue a manual hard reset.

Programming:

There is no way to access arrays in a timer routine, since arrays are private to the task. The only way around this is to save and load the array to a file.

Timer 3 seems to be buggy, at least when you start to use all 4 timers together. Then the device fails and does not respond anymore.

Debugging:

When running a program with timers, it is awkward to stop the program. You can stop the timers individually by just typing TIMER 0, STOP, this works also when the output view overwrites your input. There is a faster way to stop execution of all timers by entering a empty BASIC line, e.g. just enter 1 (make sure you use a line number you don't actually need, since this will be lost).

In the original code clean_memory() (scheduled when hitting run or editing the program) does not stop the serial interface fr calling the interpreter. Thus you need to manually stop the interface with the command close serial.

Pitfalls:

It is quite challenging to keep the BLE connection alive when you need to process data in between. This is especially true when receiving asynchronously data via UART. But this happens as well when you specify a ONREAD GOSUB statement with lengthy processing before it returns. The first goal is to keep the interrupt processing as short as possible (TI claims in its software development manual for the BLE Stack < 2ms). With BlueBasic only a few lines of code easily run longer than 2ms. Thus we need to give the control back to the stack by "task switching" essentially breaking a lengthy processing into smaller pieces. This can be done by inserting DELAY x commands to give the stack time for urgent housekeeping.

Memory space and especially the number of variables is very limited. So one way out is to utilize DIM arrays to increase the variable name space. You can reuse arrays in a GOSUB routine, since it overlays a new temporary memory space on the heap. When the interpreter give back control to the stack, this temporary space gets deallocated from heap.

In case you want a CHARACTERISTICS to send or return not only a single variable (with a fixed size of 4 bytes) you can use arrays. The number of bytes the CHARACTERISTICS uses depends on the array size. The array size is defined by the main program, so you should not use a shadow DIM array in a GOSUB routine for this variable.

10 DIM U(12)
...
1060 GATT READ WRITE U ONREAD GOSUB 2000 ONWRITE GOSUB 2500
...
2000 // using DIM U(12) here would allocate new memory which will not be returned to the stack!
2000 U(0) = 1
2010 U(1) = 2
...
// after the return the array U() will be handed over to the BLE stack
2090 RETURN
...
2500 // when using DIM prior getting the data, you have no access to the data anymore
2510 PRINT U(0),",",U(1),",",U(2)
2520 RETURN

You can however use U() in a different subroutine via DIM U(8) for new memory which will not conflict with the previous CHARACTERISTICS.

When using DIM multiple times with the same variable name in the main program (outside from GOSUB) it will eat up the heap space.