tinyTag Development Board
 |
Self contained, complete developement platform for sensing, automation, IoT in general. Features:
|
Contents
Quick Start Up Guide
The board comes pre-loded with a SmartBasic engine. This engine acts as an OS, exposing a simple file system (for storing applications) and a minimal AT command interpreter. The AT commands are used for loading and running an application, for managing the file system etc.
To operate the tinyTag a simple connection to an USB port is needed. tinyTag has an USB to serial interface on the break-off part.
On the software side UwTerminalX is the recommended application. It is an open source, freely available tool, which can serve two goals: communication (includes downloading projects to tinyTag) and compiling SmartBasic projects. To be accurate, UwTerminalX is using the compiler (an external application) behind the scenes to build the application, then downloads the resulted code into the tinyTag. Follow the instructions at the link above to install the tool.
Remark: The instructions on this page assume a Windows PC as development platform. Linux or Mac is also possible, however there are a few differences to be considered.
The first AT commands
- On the tinyTag set the Battery operation switch to OFF position (away from ON), and the Autorun switch to Interactive position
- Connect an USB cable between PC and tinyTag
- Start UwTerminalX. First screen will ask for agreement to license. If accepted, the next screen shows configuration: COM port + parameters. tinyTag is visible as a virtual COM port. Communication parameters: 115200, 8N1, with CTS/RTS handshaking. Device is BL65x, as tinyTag is using a BL652 module. Click OK when done.
- A terminal window is presented and the module answers with 00. If not, press ENTER - the module should answer with 00, indicating "ready to accept commands". (All AT commands end with ENTER.)
"00" received is a confirmation that the setup is complete, correct and can be used for development.
From the many AT commands supported by the SmartBasic engine, the following are the most used during development:
- AT i 3 - returns the version of the SmartBasic engine (As of May 2021, the newest version is 28.11.8.0r1)
- AT i 6 - returns the size of the file system and the amount of free space (for storing applications)
- AT+dir - list the applications stored in the file system (available into tinyTag and ready to run)
- AT+run "app_name" - starts app_name if app_name is an application available in the file system, otherwise signals error
- AT & f* - erase the complete file system and reset parameters saved in NVM to default values
- AT & f1 - erase the file system, keeping values of NVM parameters
All the above AT commands and typical tinyTag responses are visible in the screenshot below.
In this case, the scanner application was already preloaded: Therefore the available space (80094 bytes) is smaller than total file system space (81920 bytes). The next screenshot shows erasing the file system.
SmartBasic Compiler
The compiler is used behind the scenes by the UwTerminalX application. Each SmartBasic version has a matching compiler. This means, every time the SmartBasic engine on the tinyTag is updated, the matching compiler must be fetched. UwTerminalX has a sub-folder "Compilers" for storing the compilers. See the picture below.
When the user triggers the compilation of an app, UwTerminalX reads out the version of the SmartBasic engine on the tinyTag, attempts to locate the matching complier and then to build the application. If the compiler is not found, an error is triggered and the compilation is aborted.
SmartBasic engine is continuously evolved; every upgrade package contains both the SmartBasic engine for the tinyTag and the matching compiler. Select one of the *Firmware*.zip files in the Resources section, save it locally, unzip it and check the Firmware sub-folder. There is an application BL65xUartFwUpgrade.exe which can be used to upgrade the tinyTag to that specific SmartBasic version. In the same sub-folder the matching compiler is to be found - XComp-BL652_*.exe. The compiler must be copied to the folder Compilers of UwTerminalX.
At this point, the famous "Hello World" program can be created and run. Open a text editor and add the code below:
print "Hello World!\n"
Save the file as "helloWorld.sb". (.sb is the preferred extension for SmartBasic files. However it is not mandatory.)
Right ckick in UwTerminalX, select "Compile+Load", select the helloWorld.sb file - the file is compiled and loaded into tinyTag. AT+dir will show the app in the file system. AT+run "helloWorld" will launch the application. The screenshot below shows the expected output.
At this point, a walk through all stages of development flow is completed. Next sections will bring in more details and will progressively increase the code complexity.
Development Flow
The development starts by writing the application. Then the application is compiled and finaly download into tinyTag, where it can be run.
The sequence above is executed iteratively until the application behaves as intended.
Writing the code can be done with any text editor. Notepad++ is one of the preferred choices, as it has syntax highligting. To enable it, select "Language" menu, "Define your language..." and then "Import" the file smartBASIC(notepad++).xml, which is part of the SmartBasic ugrade packages (see Resources). Finally restart Notepadd++. The procedure is described in more details in this application note.
Compilation and download steps can be combined into a single step. In picture above, step 1 shows bringing in the "right click" menu and selecting one of the top 3 options. Usually "XCompile + Load" to compile the app and load it into the tinyTag, or "XCompile + Load + Run" to trigger its execution after loading. Step 2 above shows the result of a successful compilation and loading.
Remark: In case of syntax errors the compilation process is interrupted and there is no loading into tinyTag. The first error encountered is highlighted together with a minimal description.
Debugging
While developing, it is often necessary to inspect what is going on inside the tinyTag/application. SmartBasic is limited in this perspective. Debugging is done using print statements. See a typical example below:
print "var x = "; x; " and y = "; y; " \n"
Print command allows creating a complex message by concatenation. Various fields separated by ; are simply concatenated into a single message and printed out via serial interface (UART).
When development is completed, care must be exercised to remove all debug messages from code. The first debug message left in code will enable the UART, which means a continuous current draw (some mA - relevant for battery operation!).
An alternative debugging method is to use a GPIO and toggle it a number of times. Additionally an oscilloscope is needed to observe the GPIO toggling. This approach has a much lower impact on the application timing. The main idea is to indicate various runtime conditions by certain numbers of togglings. See the example below:
#define DIGITAL_OUT 2
#define OUT_LOW 0x00
#define OUT_HI 0x01
#define STRGLO_STRGHI 0x30
#define SIO_20 20
DIM a, errCode
SUB GPIO_toggleN(byVal n as INTEGER)
dim i
for i = 1 to n
GpioWrite(SIO_20, OUT_LOW)
GpioWrite(SIO_20, OUT_HI)
next
GpioWrite(SIO_20, OUT_LOW) // at the end ensure line is left in low state
ENDSUB
// the equivalent of main() function in a .c program starts here
a = 5
// configure the pin as output; start with pin set to low
errCode = GpioSetFunc(SIO_20, DIGITAL_OUT, STRGLO_STRGHI | OUT_LOW)
if (5 == a) then
GPIO_toggleN(5)
else
GPIO_toggleN(1)
endif
Simply copy the code above, compile + load + run and observe SIO_20 with the scope. The scope should capture something similar to the screenshot below:
Play around with the value of a and see what changes.
tinyTag can talk to a mobile phone, or raspberry PI via Bluetooth. Debugging Bluetooth communication is done using external tools. One of the most affordable tools is nRF Connect for Mobile - a freely available application running on Android. This means it can transform a regular Android phone into a very powerful debugging instrument. nRF Connect allows observing if tinyTag is sending something out, whether the data sent is the expected data or something else and much more.
As an example, below are presented a few screenshots from nRF Connect showing a list of devices detected during scanning, a closer look into the raw date sent by device CF:09:C8:AA:36:BB and the last capture showing the history of transmitted data.
SmartBasic
SmartBasic is similar to Basic languages from 70' - 80', extended to support modern technologies and microcontrollers. Statements are interpreted and executed line by line.
A SmartBasic application could be very short, completely defined in a single file or it can be quite complex, spreading across several files (modules). An essential detail to be considered: once something is defined (like a variable, or function etc.), it is available (visible) in all subsequent code, including imported modules following the definition.
SmartBasic is intended for event based programming. This means the system spends most time on sleep, waiting for an event. When an event is triggered, the system wakes up, executes the event handler and returns to sleep. Therefore the application must be designed for event based operation.
SmartBasic includes (has support for):
- variables, constants
- control statements (conditionals and loops)
- error and event handling
- a large set of built in routines
The ultimate reference on what is available, syntax and usage examples, is the user guide - core functionality (see Resources).
In addition to core functionality, SmartBasic includes a set of extensions for Bluetooth operation, as the platform is intended for Bluetooth applications. The reference is included in the second .pdf from Resources section.
Simple SmartBasic application
As an example, a simple application (completely defined in a single file - see simpleApp.sb in Resources) is presented below. The application defines a routine to toggle an GPIO n times (useful for debugging).
The application runs in a loop. It generates a random number of seconds to be used as a sleep interval. Then it toggles the GPIO to indicate the number of seconds and also prints the number over the serial interface. Finally it sleeps for that number of seconds. When time is elapsed, the app wakes up and the loop is repeated.
The structure highlighted above is the same, whether the application is completely defined in a single file or spread across several modules. WAITEVENT statement appears only once, in the "main" fucntion. Everything used in the code must be defined before or must be part of the SmartBasic functionality (core or extensions).
Complex SmartBasic application
In a complex application, a sensitive code partitioning in different modules is required. Remember: everything defined is avaialble in all sub-sequent code, including imported modules. When the application grows this could lead to a mess. Therefore is preferred to work as much as possible with local (function, subroutine level) variables, so that the risk of accidentally changing something just because it is accessible, is minimized. Another trick is to encapsulate related functionality into a module and keep it grouped. The access to module's data should be done through a set of defined functions (module interface), even if the relevant variables would be directly accessible.
As an example, below is presented a slightly more complex application, which is periodically reading out the pressure & temperature values from DSP310 sensor and then is printing them out over the serial interface.
It consists of the 4 modules depicted above. The main module is the application core - is the point where the execution starts and includes the "main" function. The sensor driver is implemented in its own module - DPS310.sb. The remaining 2 modules: gpio.sb and globals.sb include global constants and definitions and GPIO related definitions. The complete application is available in the Resources section.
The application is using timer 3 to trigger a new pressure measurement every 2 seconds. The DPS310 driver is implemented as a self running unit. Once triggered, it performs a complete measurement, handling behind scenes various sensor states, timings and messges. At the end, the values are processed and stored in the module's internal variables. The DPS310 driver notifies the application by posting a message, once the measurement and processing are completed. The application can retrive the newest measurement through the module's interface (see the trick/recommendation above).
The screenshot below shows a typical output (pressure values depend on location and weather; this sample application does not consider the weather conditions when calculating the altitude).
While the application is running, it worths moving upward/downward the tinyTag board (e.g. +10cm higher, +20cm higher) and observing the sensor readings. This simple exercise gives a direct impression on the incredible sensitivity of DPS310.
Resources
Remarks
- SmartBasic - a limited number of versions are available on this site.
- v28_11_8_0_r1 - latest as of May 2021
- v28_9_5_0_r0 - the version available on the tinyTags distributed for the IMM2021 challenge
For more documentation, or looking for the absolutely latest firmware, check the following link: https://www.lairdconnect.com/wireless-modules/bluetooth-modules/bluetooth-t5-modules/bl652-series-bluetooth-v5-nfc-module.