Libraries
Background
Tollos is wholly written in C and includes the following libraries.
There are also device libraries which provide the ‘glue’ between
the Tollos libraries and the hardware.
Tollos library
This libary is called tollos, and is accessed by including tollos.h. It comprises the following modules (.c files with corresponding .h files).
Click on the module name for a more detailed description of the functions in the module.
The Tollos module is the core of the system; its primary function (sysStartup) sets up the hardware and runs the application as follows:
- initialize C statics
- initialize Interrupt Vector table in RAM
- initialize stack footprints (used for reporting stack usage)
- initialize processor clocks, PLL, etc.
- set up the default tick time (40 ms = 25 Hz)
- invoke the application init() function
- thereafter invoke the application tick() function at the appropriate interval.
Also provided are the following functions:
- sysPause – delay for a number of milliseconds
- sysQuery – query system values (tick interval, stack usage, CPU usage, etc.)
- sysSet – set system values (such as the tick interval, watchdog timeout, etc.)
- sysVector – set or cancel an interrupt handler.
Simple interface to 3-axis accelerometers.
- accGetXYZ – read latest x, y, and z accelerations
- accInit – configure and initialize accelerometer
- accRange – change range of accelerometer
- accRate – change update rate of accelerometer
- accStop – stop and power-down accelerometer
Controls digital I/O bit(s) as available:
- bitDisable – disables interrupts for a bit
- bitEnable – enables interrupts for a bit
- bitExist – tests whether one or more bits exist in a port
- bitQuery – returns the state of one or more bits in a port
- bitSet – changes one or more bits in a port to ON, OFF, or INVERT, or changes their mode.
Provides communications with a host computer, if available. The functions are:
- debugBaud – change communications baud rate (the default is 115,200 baud)
- debugf – a small version of printf that writes a formatted string to a terminal emulator on the host
- debugGet – get a character from the host (if available, otherwise returns 0).
Numerous functions for drawing to a screen, including:
- graphics – drawing pels, lines, boxes, circles and ellipses, and simple fills
- text – write character, write formatted string; proportional and other fonts are supported
- reading and writing individual pels, querying and setting state, etc.
Three fonts are included with Tollos: a 5×7 monospace (default) ASCII font, a compatible 7×7 proportional font, and an unspaced 8×12 “IBM PC” 256-character font.
Simple interface to 3-axis gyroscopes.
- gyroGetXYZ – read latest x, y, and z angular rates
- gyroInit – configure and initialize gyroscope
- gyroRate – change update rate of gyroscope
- gyroStop – stop and power-down gyroscope
- gyroTemperature – return current gyroscope die temperature
Functions to read and write data from I2C bus devices, in I2C master mode (the microcontroller is the Master):
- Get and Put functions – read or write one or more bytes from registers (using the convention of first data byte written is register address)
- i2cPutGet – write an arbitrary number of bytes followed by a read of an arbitrary number of bytes (this is the ‘low level’ I/O supported by I2C)
- i2cScan – a test/debug function to scan an I2C channel for devices.
Controls on-board LED(s) as available:
- ledQuery – returns the state of a LED
- ledSet – changes a LED to ON, OFF, or INVERT.
Functions to use UART serial communications devices.
- uartGetc – get character from UART device
- uartInit – initialize serial UART device
- uartPutc – send character to UART device
TollosUtil is a small set of utilities (functions and macros):
- functions: byte2hex, fastrand (random integers), hex2byte, isqrtg (fast integer square root), i2str (layout integer), nop, streq (caseless compare), strf (string formatter)
- macros: abs, iswap, max, min, signum.
The vcom functions provide character I/O over a USB link (Virtual COM port).
- vcomGetc – get character from vcom device
- vcomInit – initialize serial vcom device
- vcomPutc – send character to vcom device
- vcomStop – stop the vcom device
The miniDec module supports a simple decimal format, ‘dec’, intended for the storage, management, and display of decimal data. As such, it provides functions for conversions to and from ints, doubles, and strings in various forms, along with decQuantize to ‘shape’ decimal data. Additional functions allow detailed inspection and manipulation of decimals.
Arithmetic operations are currently not included, but the bounds of the format conform to IEEE 754 rules (section 3) and IEEE 754 arithmetic functions could be added later.
The strf string formatter in tollosUtil can include dec data
using the %m format code.
Other libraries
(These are currently running under an earlier version of Tollos, in an experimental avionics device; these will be documented when fully ported to Tollos and mbed and tested.)
tollosGPS – high-level access to a GPS device with a ring buffer of messages, etc.
tollosSensors – accelerometer, gyro, etc. – the generic interfaces will be moved to the tollos library; specific device glue functions will move into their own library (e.g., ADXL345, ITG3200)
tollosGeog – geographic library (bearings and distances from GPS positions)
tollosMenu – a simple menu system