Data Collection

The ICOtronic package provides two different options to collect sensor data with the ICOtronic system:

  1. Use the API to write your own Python scripts.

  2. Use the icon script to collect data: We will describe how to measure some basic data with this script in the text below

Note: Since ICOn currently only provides very basic functionality for data collection you might be happier using one of the tools below:

  • ICOapi: A RESTful API for using the ICOtronic system via HTTP

  • ICOweb: A frontend/client developed in conjunction with the corresponding ICOapi backend. It is designed to be run in any form of modern browser.

  • ICOdaq: A closed source Electron application for Windows (based on ICOapi & ICOweb)

  • ICOc: A text based UI for Windows, based on an older deprecated version of the ICOtronic library.

Sensor Node Identifiers

To connect to a sensor node (SHA, STH, SMH) you need to know an identifier for the node, which can be one of the following:

  • Bluetooth advertisement name: up to 8 characters, no special characters allowed

  • Bluetooth MAC address: 8 Bytes, usually written in hexadecimal format

  • Node number: starting with 0, up to the number of available sensor nodes minus one (e.g. for 8 sensor nodes, the maximum sensor node number will be 7)

If you do not know any of the above identifiers for your sensor node you can use the command

icon list

to show the available nodes:

🤖 Name: Test-STH, Number: 0, MAC Address: 08-6B-D7-01-DE-81, RSSI: -51

In the example above, we see that one sensor node is available with the following identifiers:

  • node number: 0

  • name: Test-STH

  • MAC address: 08-6B-D7-01-DE-81

Note: The last value “-51” of the example output is the current received signal strength indication (RSSI).

Collecting Data

After you determined one of the identifiers (name, MAC address, node number) of your sensor node you can use the command:

icon measure

to collect measurement data. For example, to collect data from an STH with the name “Test-STH” for 10 seconds you can use the following command:

icon measure --name Test-STH --time 10

After the measurement took place the command will print some information about the collected data, including the location of the HDF5 measurement file:

Sample Rate: 9523.81 Hz
Data Loss: 0.0 %
Filepath: Measurement_2025-05-14_15-11-25.hdf5

By default measurement files will be stored in the current working directory with

  • a name starting with the text Measurement

  • followed by a date/time-stamp, and

  • the extension .hdf5.

Measurement Data

Note: ICOn assumes that the sensor node always measures acceleration data in multiples of the gravity of earth, commonly referred as \(g\) or \(g_0\). While this is true for most of the sensor hardware (such as STHs), some sensor nodes measure other values, e.g. force or temperature. Even in this case the measurement software will (incorrectly) convert the data into multiples of \(g\). We are working on adding support for configuring the sensor type in the firmware and the ICOtronic package to fix this issue.

To take a look at the measurement data you can use the tool HDFView.

Note: Unfortunately you need to create a free account to download the program. If you do not want to register, then you can try if one of the accounts listed at BugMeNot works. Another option is to download the application from here. Just click on the folder for the latest version of the application (hdfview-…) and afterwards on the folder bin to see a list of compressed binaries (.zip & .tar.gz) for the different supported operating systems.

The screenshot below shows a measurement file produced by the ICOtronic library:

Main Window of HDFView

As you can see the table with the name acceleration stores the acceleration data. The screenshot above displays the metadata of the table. The most important meta attributes here are probably:

  • Start_Time, which contains the start time of the measurement run in ISO format, and

  • Sensor_Range, which specifies the range of the used acceleration sensor in multiples of earth’s gravitation (g₀ ≅ 9.81 m/s²).

After you double click on the acceleration table on the left, HDFView will show you the actual acceleration data:

Acceleration Table in HDFView

As you can infer from the x column above the table shows the acceleration measurement data (in multiples of g₀) for a single axis. The table below describes the meaning of the columns:

Column

Description

Unit

counter

A cyclic counter value (0–255) sent with the acceleration data to recognize lost packets

–

timestamp

The timestamp for the measured value in microseconds since the measurement start

μs

x

Acceleration in the x direction as multiples of earth’s gravitation

g₀ (≅ 9.81 m/s²)

Depending on your sensor and your settings the table might also contain columns for the y and/or z axis.

If you want you can also use HDFView to print a simple graph for your acceleration data. To do that:

  1. Select the values for the the ordinate (e.g. click on the x column to select all acceleration data for the x axis)

  2. Click on the graph icon in the top left corner

  3. Choose the data for the abscissa (e.g. the timestamp column)

  4. Click on the “OK” button

The screenshot below shows an example of such a graph:

Acceleration Graph in HDFView

For a more advanced analysis of the data files you can use our collection of measurement utilities ICOlyzer.

Adding Custom Metadata

Sometimes you also want to add additional data about a measurement. To do that you can also use HDFView. Since the tool opens files in read-only mode by default you need to change the default file access mode to “Read/Write” first:

  1. Open HDFView

  2. Click on “Tools” → “User Options”

  3. Select “General Settings”

  4. Under the text “Default File Access Mode” choose “Read/Write”

  5. Close HDFView

Now you should be able to add and modify attributes. For example, to add a revolutions per minute (RPM) value of 15000 you can use the following steps:

  1. Open the measurement file in HDFView

  2. Click on the table “acceleration” in the left part of the window

  3. In the tab “Object Attribute Info” on the right, click on the button “Add attribute”

  4. Check that “Object List” contains the value “/acceleration”

  5. Enter the text “RPM” in the field “Name”

  6. In the field “Value” enter the text “15000”

  7. The “Datatype Class” should be set to “INTEGER”

  8. For the size (in bits) choose a bit length that is large enough to store the value. In our example everything equal to or larger than 16 bits should work.

  9. Optionally you can also check “Unsigned”, if you are sure that you only want to store positive values

  10. Click the button “OK”

HDFView: RPM Attribute

Sometimes you also want to add some general purpose data. For that you can use the “STRING” datatype class. For example, to store the text “hello world” in an attribute called “Comment” you can do the following

  1. Repeat steps 1. – 4. from above

  2. Choose “STRING” as “Datatype Class”

  3. Under “Array Size” choose a length that is large enough to store the text such as “1000” (every size larger than or equal to 11 characters should work)

  4. Click the button “OK”

HDFView: Comment Attribute

If you want you can also add multiline text. Since you can not add newlines using ⏎ in HDFView directly, we recommend you open your favorite text editor to write the text and then copy and paste the text into the value field. HDFView will only show the last line of the pasted text. However, after you copy and paste the text into another program you will see that HDFView stored the text including the newlines.