LoggerBIT Firmware

Firmware to create a data logger for BITalino (r)evolution based on the OpenLog by SparkFun

Programming the OpenLog with the LoggerBIT firmware

Loading the LoggerBIT firmware onto the OpenLog is the first thing to do. This process must be done without making any physical changes to the OpenLog board that is currently shipped by SparkFun.

Download the Arduino IDE version 1.6.5, a verified known good version.
Download the LoggerBIT firmware.
Download the required libraries:
- Bill Greiman's SerialPort library with the required modifications already included
- Bill Greiman's SdFat library
Install the libraries into Arduino. Check here for more detailed instructions on how to do it.
Connect the OpenLog to the computer via an FTDI board. Check here for more detailed instructions on how to make the connection between the two boards.
Open the LoggerBIT sketch with the Arduino IDE, select the Arduino/Genuino Uno board setting under Tools>Board, and select the proper COM port for the FTDI board under Tools>Port.
Upload the code and it's done! Proceed to the hardware changes in the OpenLog board.

What to change in the OpenLog board for using hardware flow-control

Once the OpenLog is loaded with the LoggerBIT firmware, the board has to be physically adjusted, by including the necessary extra wiring, so the hardware flow-control mechanism can properly function.

You will need:

A male header with 6 pins (right angle)

Thin wire (for the shunt)
Soldering iron and thin solder

Firstly, bend the rightmost pin of the header, so that it stays in a straight horizontal direction instead of the original right angle.

Afterwards, place the header on the pads of OpenLog UART interface (at the bottom), so that the bent pin stays over the GRN pad (you may need to clip the bent pin so that it does not go beyond the pad). Solder each of the 5 remaining pins with the corresponding pad.

Solder one end of the shunt directly on the 2nd pin from the right, on the top side of the MCU and the other end to the header pin that hangs above the GRN pad. Make sure that there is no solder touching the GRN pad, it has to remain not connected.

How to connect BITalino to the OpenLog board

The pin ordering of the OpenLog UART interface allows for the it to be directly connected with the MCU board of the BITalino. However, to ensure that all connections are properly done and that the TX and RX pins are switched, the OpenLog must be plugged in with the microSD card facing up to the top side of the BITalino’s MCU (the one where the microcontroller’s chip is soldered).

How to configure the BITalino acquisition settings

To begin with, place the configuration file on the root of a freshly formatted microSD card. For formatting, use the oficial SD memory card formatter tool from the SD Association.

This configuration file has has two lines: one for the settings and the other for making it user-friendly by indexing their definitions.

1000,live,123456,00,00
sampling rate,mode,channels,trigger,digital IO

The possible settings to configure are defined as follows:

sampling rate - The sampling rate, in Hz, in which to acquire data, with possible values being 1, 10, 100 and 1000.
mode - The BITalino's state of operation, it can be either live or simulated. In live mode the device will acquire and stream data in real time, whereas in simulated mode, mostly aimed at developers, it streams synthetic data generated by the firmware (sine, saw tooth, square waves and pre-recorded electrocardiography time series).
channels - Which analog channels to acquire, from the 6 available ones. This parameter is defined as a number, in which each digit corresponds to the analog channel of equivalent numeral. For example, if you wish to acquire the first, third and fifth analog channels, then this option should be set as 135. At most, you can choose to acquire all channels, by setting this parameter as 123456 , and at least, it is possible to not sample any analog channel, by leaving this setting empty. Considering this, possible values for this argument range all the combinations, without repetion, that can be made from the 6-element set.
trigger - This setting is used to indicate whether the data logging to the SD card should initiate immediately or only when a variation is detected in one (01 or 10) or both (11) digital inputs of the BITalino. This parameter can be useful, for instance, if you wish to initiate the logging by pressing a push button. It is a 2-digit number, in which the tens and units digits correspond to digital inputs I1 and I2, respectively. It should be noted that both inputs are active-low. As such, for example, if this argument is set as 10 then the logging will only begin when a change is detected in digital input I1, i.e., when there is a transition from HIGH to LOW in that pin.
digital IO - The initial state of the digital outputs pins O1 and O2. Similarly to what occurs with the trigger command, this is also a 2-digit number, in which the tens and units digits correspond to digital outputs O1 and O2, respectively. If, for instance, it is defined as 01, the digital output pin O2 is set HIGH and the other one is set LOW.

Recommended microSD cards

While developing the LoggerBIT firmware we tested different types of cards. Because we operate at high baud rates (115200 bps), it is recommended to use a card with specifications equivalent to or greater than those of cards from the SDHC format with UHS-I Class 3 (U3) ratings.

The card that best performed in our benchmarks was the one from the figure below, with a write speed of up to 90MB/s.

Decoding the stored data

To optimize the performance, the LoggerBIT firmware stores the data in binary format (.BIN), reason for which we provide a decoding tool. The decoder is a Python script that converts the .BIN files generated by the OpenLog into .TXT (ASCII) files that are compatible with the OpenSignals (r)evolution software. For each .BIN file, its corresponding .TXT file is created. At the end of execution, a single .LOG file is also created, that contains, per file, some useful informations about the decoding process, such as:

number of channels configured for acquisiton
sampling rate
acquisition mode
total sampling time
total decoding time
number of failed packet receptions
total number of lost packets

Arguments

The decoder can convert a single .BIN file at a time, or an entire folder (including its subdirectories) where multiple .BIN files may reside. As such, it accepts 1 out of 3 arguments:

-h, --help              show this help message and exit
-p PATHNAME, --pathname PATHNAME
                        the pathname of the folder to decode
-f FILENAME, --filename FILENAME
                        the filename of the single file to decode

One of the arguments -p/--pathname -f/--filename is always required.

How to run the decoder?

The decoder can be executed as a script or treated as a module that can be imported. Below there are examples of how to run it for a single file, for both types of execution.

Script

python decoder.py -f "C:\Users\margarida\logs\LOG00000.BIN"

Module

import decoder
decoder.main([r'-f C:\Users\margarida\logs\LOG00000.BIN'])

Acknowledgments:

This work was partially supported by the IT – Instituto de Telecomunicações under the grant UID/EEA/50008/2013 "SmartHeart" (https://www.it.pt/Projects/Index/4465).

BITalinoWorld/firmware-loggerbit