Robobot teensy firmware

Back to Robobot

Teensy firmware

The board and the primary functional modules.

Each module is a class and instantiated with a global name, as shown below the module name in brackets.

The source code filename is mostly the same as the global name but is preceded by the character 'u'.

All sensor modules extensively use Arduino libraries.

Interface

All communication with Teensy is text-based, including both commands and replies.

A complete list of commands to the Teensy can be found here: Help page Teensy_8

This description is between the tteensy_interface and the Teensy. Most commands and data are also available from MQTT, see Robobot MQTT topics.

Subscription

Sensor data are available on a subscription basis, e.g. to get gyro data every 50 ms use:

sub gyro 50
;39gyro 0.122865 0.040497 -0.355164 14948.748
;27gyro -0.151793 -0.051056 -0.233093 14948.799
;27gyro -0.060240 -0.295197 -0.172058 14948.848
;51gyro 0.092348 0.162567 -0.294128 14948.897
;27gyro -0.121275 -0.020538 -0.385681 14948.948
;25gyro -0.029723 -0.234161 -0.233093 14948.998

All subscriptions start with sub followed by the keyword for the data and ending with the data interval in ms. The fastest update rate is determined by the update rate of the Teensy, typically 2ms.

The USB interface can handle about 4000 messages per second.

The data is preceded with three characters ';99', a simple validity check to ensure half messages are not used (e.g. if the interface is overloaded). The teensy_interface will check and remove these characters.

The remaining part is the data preceded with a unique keyword (here, "gyro"). The data string is sometimes extended with additional (debug) data; here, the fourth value is a timestamp (Teensy time).

All subscribable data can be requested once by adding an 'i' at the end of the keyword; like:

gyroi
;69gyro 0.000795 -0.081573 -0.172058 15693.118

Remove the leading three characters

If data directly from Teensy is to be loaded into MATLAB, then the first three characters need to be removed. SED can do the task.

E.g. if the file is teensy_log.txt looks like this:

;89# processing under protest - no CRC 'log'
;88%  1    time 0.0031 sec, from Bode (122)
;26%  2  3 Motor voltage (V) left, right: 0.00 0.00
;54%  4  5 Wheel velocity (m/s) left, right: -0.0000 0.0000
;20%  6    Turnrate (rad/s): 0.0000
;96%  7  8  9 10 Pose x,y,h,tilt (m,m,rad,rad): 0.0000 0.0000 0.0000 3.1356
;81% 11 .. 29 Edge sensor: left pos, right pos, line valid, crossing, values d d d d d d d d,  white, used, LED high, average white, line detect count, crossing detect count
;22% 30    Battery voltage (19.15 V)
;950.0031 0.00 0.00 -0.0000 0.0000 0.0000 0.0000 0.0000 0.00000 3.13556 0.00 0.00 0 0 590 563 568 550 558 544 542 604  1 1 1 0.57 0 0 19.15 
;080.0071 0.00 0.00 -0.0000 0.0000 0.0000 0.0000 0.0000 0.00000 3.13555 0.00 0.00 0 0 609 584 559 575 557 531 515 546  1 1 1 0.56 0 0 19.14 
;050.0111 1.53 1.53 -0.0000 0.0000 0.0000 0.0000 0.0000 0.00000 3.13554 0.00 0.00 0 0 589 583 563 565 532 532 540 552  1 1 1 0.56 0 0 19.10

Then the first line starting with '#' need to be removed, that is easy in an editor, the three crc characters need to be removed too.:

sed -i 's/^.\{3\}//' teensy_log.txt

will do the job, now it is:

%  1    time 0.0031 sec, from Bode (122)
%  2  3 Motor voltage (V) left, right: 0.00 0.00
%  4  5 Wheel velocity (m/s) left, right: -0.0000 0.0000
%  6    Turnrate (rad/s): 0.0000
%  7  8  9 10 Pose x,y,h,tilt (m,m,rad,rad): 0.0000 0.0000 0.0000 3.1356
% 11 .. 29 Edge sensor: left pos, right pos, line valid, crossing, values d d d d d d d d,  white, used, LED high, average white, line detect count, crossing detect count
% 30    Battery voltage (19.15 V)
0.0031 0.00 0.00 -0.0000 0.0000 0.0000 0.0000 0.0000 0.00000 3.13556 0.00 0.00 0 0 590 563 568 550 558 544 542 604  1 1 1 0.57 0 0 19.15 
0.0071 0.00 0.00 -0.0000 0.0000 0.0000 0.0000 0.0000 0.00000 3.13555 0.00 0.00 0 0 609 584 559 575 557 531 515 546  1 1 1 0.56 0 0 19.14 
0.0111 1.53 1.53 -0.0000 0.0000 0.0000 0.0000 0.0000 0.00000 3.13554 0.00 0.00 0 0 589 583 563 565 532 532 540 552  1 1 1 0.56 0 0 19.10

Ready for MATLAB import, e.g.:

dd = load('teensy_log.txt');

CRC check

The data is preceded by three characters: ';99' when a CRC check is used. The teensy_interface will check and remove these characters, but this is annoying if you talk interactively to the firmware using a console, e.g., Putty.

The CRC insert and check can be removed by sending:

i 1
>>

This will make the teensy echo all the characters received back to the console and turn off the CRC.

The Teensy will reply with a >> prompt for commands. The feature can be turned off by:

i 0

The Teensy will stop the USB data stream if no messages are received within 60 seconds. This function is not active if CRC is disabled.

The Teensy interface will reject all data if CRC is disabled.

Configuration

Commands to the teensy are like:

motv 3 3

setting the motor voltage to 3V for both motors. Note: this command are only usable, if the teensy_interface app is not running, as this controls the motor voltage.

leds 16 100 100 0

sets LED number 16 to yellowish, red=100 (out of 255), green=100, blue=0

irc 15000 5000 15500 6300 1

This sets the IR distance sensor calibration values. 15000 is the AD value for a 13cm target and 5000 for a 50cm target. The following two are for sensor 2 (normally forward-looking). The last '1' is to leave the sensor on (it uses about 30mA).

Some configurations can be saved in a configuration flash:

eew

All commands known by Teensy are listed here Help page Teensy 8, but they are also available online with the help command.

Commands should be preceded with the same three-character CRC check as outgoing messages (unless CRC is turned off), but the Teensy will accept commands without - with a complaint:

leds 16 100 100 0
;67# processing under protest - no CRC 'leds 16 100 100 0'
;87# set LED 16 to 100 100 0

Information and debug

Information and debug messages are always preceded by a '#' character, as shown above.

Log data

There is a log-to-RAM feature

lognow 100

The log now 100 will start logging (until the buffer is full). Something like 300 kbytes has been allocated for logging.

The logged data can be retrieved by

log
%  1    time 0.0000 sec, from Bode (122)
%  2  3 Motor voltage (V) left, right: 0.00 0.00
%  4  5 Wheel velocity (m/s) left, right: -0.0000 0.0000
%  6    Turnrate (rad/s): 0.0000
%  7  8  9 10 Pose x,y,h,tilt (m,m,rad,rad): 0.0000 0.0000 0.0000 3.1307
% 11 .. 29 Edge sensor: left pos, right pos, line valid, crossing, values d d d d d d d d,  white, used, LED high, average white, line detect count, crossing detect count
% 30    Battery voltage (15.68 V)
0.0000 0.00 0.00 -0.0000 0.0000 0.0000 0.0000 0.0000 0.00000 3.13067 0.00 0.00 0 0 0 0 0 0 0 0 0 0  1 1 1 0.00 0 0 15.68 
0.0020 0.00 0.00 -0.0000 0.0000 0.0000 0.0000 0.0000 0.00000 3.13066 0.00 0.00 1 0 738 701 758 814 740 684 703 877  1 1 1 0.75 0 1 15.68 
0.0040 0.00 0.00 -0.0000 0.0000 0.0000 0.0000 0.0000 0.00000 3.13063 -0.88 -0.88 1 0 651 712 814 838 725 616 627 709  1 1 1 0.71 0 2 15.67 
...
0.1140 -0.62 4.62 -0.0000 0.0000 0.0000 0.0007 0.0000 0.00637 3.13009 -1.03 -1.03 1 0 626 755 921 925 743 586 568 561  1 1 1 0.71 0 20 15.56 
0.1160 -0.56 4.56 -0.0000 0.1917 0.8157 0.0009 0.0000 0.00797 3.13027 -1.02 -1.02 1 0 623 750 918 940 736 586 561 553  1 1 1 0.71 0 20 15.57 
0.1180 -0.54 4.54 -0.0000 0.2329 0.9910 0.0011 0.0000 0.00956 3.13030 -1.02 -1.02 1 0 615 749 913 926 738 600 571 546  1 1 1 0.71 0 20 15.56 
0.1200 -0.49 4.49 -0.0000 0.2707 1.1521 0.0015 0.0000 0.01275 3.13016 -1.01 -1.01 1 0 619 745 914 941 732 580 557 551  1 1 1 0.71 0 20 15.56

The first part, starting with '%', explains the data; the following lines will start with a number [0-9] character and be numeric only.

Which data to log is controlled by log-flags:

lfls 0 0 0 0 0 1 0 0 1 1 1 1 0 1 0 0 0

The flags are: (mis), ACC, gyro, (mag), (motref), motor V *, motor A, encoder, velocity *, turn-rate *, pose *, line sensor *, distance, battery *, timing, extra, (chirp). Data types in brachets are not available in this version of the firmware. Those marked with an '*' are selected by default. Selection will be saved with the eew command.

Matlab

This format is intended for Matlab, as Matlab will ignore lines starting with a '%'. The rest can be loaded with the Matlab load command:

dd = load('filename.txt');

If the load fails, there are probably other types of lines. A text editor can remove such lines.