HyperIMU Documentation

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.

axis_info.png

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:

HimuMain
HyperIMU’s main screen
  1. Drawer Main Menu : for the app configuration and more
  2. HyperIMU wheel : starts/stops HyperIMU
  3. Console : shows online additional information
  4. 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.

pharos
HyperIMU pharos setup


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 commandDescriptionServer Response
enter hostenters the Host mode for the current client if there is no active host sessionACK/NACK
exit hostexits the Host mode for the current clientACK/NACK
launchlaunches the HyperIMU main GUI without starting itACK/NACK
startlaunches and starts the HyperIMU acquisitionACK/NACK
stopstops the HyperIMU acquisitionACK/NACK
set protocol <value>sets the protocol to be used by HyperIMU for the streaming. Possible values for <value> are: TCP, UDP, NONE, JSON, FILEACK/NACK
get protocolasks for the streaming protocol currently setthe current protocol
set port <value> sets the port number for the protocols TCP, UDP and JSONACK/NACK
get portasks for the port number currently setthe current port number
set ip <value>sets the server ip address for the protocols TCP, UDP and JSONACK/NACK
get ipasks for the ip address currently setthe current ip address
set DT <value> sets the sampling rate (in ms) for the data acquisitionACK/NACK
get dtasks for the sampling rate currently setthe 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 FALSEACK/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 FALSEACK/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 FALSEACK/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 FALSEACK/NACK
enable BATT <value>enables/disables the Battery stats to be included to the stream. Possible values for <value> can be: TRUE or FALSEACK/NACK
enable persistent <value> enables/disables the connection persistency. Possible values for <value> can be: TRUE or FALSEACK/NACK
get namesasks for the lists of names of all the sensors inside the devicea csv string containing all sensors’ names
get typesasks 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 listasks 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:

ResponseDescription
ACKpositive response: the command was committed
NACKnegative response: the command was uncorrect or not allowed

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).