Contents
Overview
Technology
Designed to be as customizable as possible, HyperIMU streams the sequence of all collected sensors’ values allowing both an online and offline data processing.
Main features of HyperIMU are:
- Streaming protocols: TCP, UDP, File
- Data formatting: CSV, JSON
- Fully customizable list of sensors to stream, including both embedded sensors and geolocalization interfaces (GPS, NMEA 0183)
- Creation of multiple configuration lists for different working setups
- Customizable sampling rate for all the sensors’ signals
- Integrated signals’ charts viewer
- Responsive and user-friendly interface
- Persistent connection
Network roles
In an online data processing scenario, HyperIMU acts like a network Client, while the processing unit (MAC or PC) is the network Server.
With the persistence connection enabled, even if the Server is offline, HyperIMU will wait it to come back online without stopping.
Data formatting
Each sensor contains a group of three values. Values corresponding to axial sensors (such as Accelerometer, Gyroscope, Magnetometer …) are presented in the order XYZ.
Geolocalization values such as GPS and NMEA are grouped in threes as for the other sensors. With CSV formatting, each NMEA string consists of semicolon separated values string, in order to not be confused with the main HyperIMU CSV packet.
With CSV data formatting, all values are separated by commas, while with JSON protocol, all values are grouped in JSON array for each sensor.
A CSV packet is formatted as follows:
“Timestamp , Accelerometer.x , Accelerometer.y , Accelerometer.z , Gyroscope.x , Gyroscope.y , Gyroscope.z , Magnetometer.x , Magnetometer.y , Magnetometer.z , Orientation.x , Orientation.y , Orientation.z , Ambient_Light.x , Ambient_Light.y , Ambient_Light.z , GPS.lat , GPS.long , GPS.alt”
A JSON packet is sent via TCP protocol only, and it is formatted as follows:
{
“op”:”hyperimu”,
“Timestamp”:1518819953744,
“Accelerometer”:[0.09279 , 0.148016 , 9.7345703] ,
“Gyroscope”:[0.00313534 , -0.014384 , 0.0085291134] ,
“Magnetometer”:[-14.25 , -1 , -39.125] ,
“Orientation”:[92.046875 , -0.3125 , 0.5625] ,
“Ambient Light”:[6 , 0 , 9.8211191] ,
“GPS”:[0 , 0 , 0] ,
}
Coordinates System
According to Android documentation: the coordinate system is defined relative to the device’s screen when the device is held in its default orientation. When a device is held in its default orientation, the X axis is horizontal and points to the right, the Y axis is vertical and points up, and the Z axis points toward the outside of the screen face. In this system, coordinates behind the screen have negative Z values.
This coordinate system is used by the following sensors:
- Acceleration sensor
- Gravity sensor
- Gyroscope
- Linear acceleration sensor
- Geomagnetic field sensor
Protocols
HyperIMU uses the following sensors to stream the data:
- None (default) : packets are not streamed
- UDP : packets streamed via UDP as CSV format
- TCP : packets streamed via TCP/IP as CSV format
- JSON : packets streamed via TCP/IP as JSON format
- File : packets streamed in local .csv file
Please, read the Data Formatting section for more details about CSV and JSON formats. Acquisition files will be stored under the folder “{storage_root}\Documents\HyperIMU.ianovir\Exports\“
Packet extras
HyperIMU can stream also extra data, such as geolocation and device data. These information can be included in the packets as header (heading the sensors’ data) or trailer (trailing the sensors’ data).
Header
- Timestamp : the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC;
- MAC address : the unique identifier assigned to the network interface controller of the device;
- Battery info: useful stats about the device’s battery: battery level in percentage (100%:fully charged), the status (1:charging, 0:discharging) and the AC info (1:connected to AC, 0:otherwise).
Trailer
- GPS : latitude, longitude and altitude concerning geolocation;
- NMEA : GPS NMEA sentences, grouped three at time. A sequence of more than three sentences is split over more samples, maintaining their order. All values inside a single NMEA sentence will be separated by semicolons instead of commas.
Settings
The following settings will let you to customize HyperIMU:
- Sampling Rate : the time in milliseconds used to sample all sensors’ data;
- Server IP address : the IP address of the server to connect to (only for UDP, TCP and JSON protocols);
- Server Port number : the remote port number on which the server is listening for HyperIMU’s packets (only for UDP, TCP and JSON protocols);
- Persistent : when enable, HyperIMU tries persistently to reconnect even if the server is offline;
- Prequel Packet : when enabled, HyperIMU transmits sensors’ names (instead of their values) as first packet;
- # Terminator : when enabled, all packets end with the character ‘#’ instead of ; used for backward compatibility;
- Stay awake : when enabled, the screen will never sleep while on the main page;
- Play Sounds : enable/disable app’s sounds.
GUI
Main page
Below is the main page of HyperIMU appearing as opening the app:
- Drawer Main Menu : for the app configuration and more
- HyperIMU wheel : starts/stops HyperIMU
- Console : shows online additional information
- Live graph button : launches the chart viewer when HyperIMU is running
Drawer Main Menu
This menu provides main functionalities of HyperIMU. On the top of the menu, they are shown basic network information such as IP address and ssid name of the Wifi network to which the device is connected.
Main options in the menu are:
- Sensor List : allows to select all the physical sensors to be included in the packet. It is also possible to store configurations of checked sensors for multiple and further usages
- Packet Preview : allows to preview the packet with every single data
- Acquisitions : allows to browse, manage and view exported .csv acquisition files
- Settings (see next section) : allows to configure the app
- Pharos : allows to configure the Pharos Server
- Enable Pharos Server : when checked, the Pharos Server will respond to client sessions
- Power Optimization : by enabling this option, the power consumption will be optimized, but the Pharos Server may not serve clients requests when the device is sleeping
- Service port : the local port on which the pharos service will listen for clients’ requests
- Help : offline basic help
HyperIMU Server
HIMU Server (HyperIMU Server) is a python library covering all server-side stream protocols supported by HyperIMU. It performs basic operations such as input stream reading and csv sequence chunking.
You can find HIMU Server here, use it as reference or a starting point for your implementations.
HyperIMU Pharos
HyperIMU Pharos is a PRO feature which lets the users to configure the HyperIMU app remotely. With Pharos activated, the device acts like a network Server to which a client can send proper configuration commands.
All client commands and server responses consist of case-insensitive string sentences, sent via a TCP client/server connection.
Basically, this feature allows to:
- configure remotely all settings of HyperIMU such as protocols, ports, packet’s header and trailer
- fully configure the packet’s content, by including/excluding sensors
- start/stop the main HyperIMU acquisition
In order to configure any of the options of the HyperIMU app with HIMU Pharos, the Client must enter in host mode, that is a sort of authorization token. Changes to the HyperIMU settings are not allowed outside the host mode.It is possible to have only one Client in host mode at time.
Once the Client ends with modifications requests, it has to exit the host mode in order to close the session and run HyperIMU.
The commands supported by HIMU Pharos are:
| Client command | Description | Server Response |
|---|---|---|
| enter host | enters the Host mode for the current client if there is no active host session | ACK/NACK |
| exit host | exits the Host mode for the current client | ACK/NACK |
| launch | launches the HyperIMU main GUI without starting it | ACK/NACK |
| start | launches and starts the HyperIMU acquisition | ACK/NACK |
| stop | stops the HyperIMU acquisition | ACK/NACK |
| set protocol <value> | sets the protocol to be used by HyperIMU for the streaming. Possible values for <value> are: TCP, UDP, NONE, JSON, FILE | ACK/NACK |
| get protocol | asks for the streaming protocol currently set | the current protocol |
| set port <value> | sets the port number for the protocols TCP, UDP and JSON | ACK/NACK |
| get port | asks for the port number currently set | the current port number |
| set ip <value> | sets the server ip address for the protocols TCP, UDP and JSON | ACK/NACK |
| get ip | asks for the ip address currently set | the current ip address |
| set DT <value> | sets the sampling rate (in ms) for the data acquisition | ACK/NACK |
| get dt | asks for the sampling rate currently set | the current sampling rate in ms |
| enable timestamp <value> | enables/disables the timestamp as value to be included to the stream. Possible values for <value> can be: TRUE or FALSE | ACK/NACK |
| enable MAC <value> | enables/disables the MAC address as value to be included to the stream. Possible values for <value> can be: TRUE or FALSE | ACK/NACK |
| enable GPS <value> | enables/disables the GPS coordinates as values to be included to the stream. Possible values for <value> can be: TRUE or FALSE | ACK/NACK |
| enable NMEA <value> | enables/disables the GPS NMEA sentences as values to be included to the stream. Possible values for <value> can be: TRUE or FALSE | ACK/NACK |
| enable BATT <value> | enables/disables the Battery stats to be included to the stream. Possible values for <value> can be: TRUE or FALSE | ACK/NACK |
| enable persistent <value> | enables/disables the connection persistency. Possible values for <value> can be: TRUE or FALSE | ACK/NACK |
| get names | asks for the lists of names of all the sensors inside the device | a csv string containing all sensors’ names |
| get types | asks for the lists of types of all the sensors inside the device. A type is a constant number identifying the sensor type code. | a csv string containing all sensors’ type codes |
| set list <value> | configures the list of sensors to be included to the stream. The accepted <value> is a csv list of zeros and ones corresponding to the list of sensors contained inside the devices: sensors correponding to zeros (0) will be excluded from the stream, otherwise they will be included. The length of the list can be lower than the numer of sensors of the device. | ACK/NACK |
| get list | asks for the list of sensors included to the stream. | a csv list of zeros(0) and ones(1) corresponding to the list of sensors on board the device: sensors correponding to zeros (0) will be excluded from the stream, otherwise they will be included |
The main responses are:
| Response | Description |
|---|---|
| ACK | positive response: the command was committed |
| NACK | negative response: the command was uncorrect or not allowed |
External Links
HyperIMU is supported on Android OS devices (smartphones and tablets) and the latest version can be downloaded for free from the Google Play Store.
Snippets for the HIMU Server are actually hosted as a public Github repo.
Embedded signals’ charts are powered by AChartEngine (The 4ViewSoft Company).
