How to Use

HOW TO USE


Our products 3D Accelerometer and 3D Gyroscope are a quick and easy way of getting started with electro-mechanical sensors, without the need to bother with complicated wiring and soldering.


They will integrate easily into already existing drivers and libraries for generic sensor devices.

Linux

 

When connected to a Linux system, the sensor will automatically be identified as an IIO device (Industrial Input/Output). The interface of connected IIO sensors can be accessed through sysfs, normally at this location:

 

/sys/bus/iio/devices/

 

When you connect a new IIO-compatible sensor, it will be enumerated as iio:device0, assuming there aren’t any other already connected. Please note that some computers might have multiple built-in sensors that also communicate through IIO. If index 0 is already occupied, the lowest available number will be used, for example iio:device1, iio:device2, etc.

 

When checked for connected devices with lsusb, your Lingon Electronics devices may appear like this:

 

Bus 002 Device 006: ID 16d0:0de6 MCS

Bus 002 Device 007: ID 16d0:0de7 MCS

 

 

For the following examples, it’s assumed that your sensor is enumerated as /dev/iio:device0 (IIO device index 0) when connected.

 

IIO sensor parameters

 

The sensor will appear as a folder in the file system. To view a full list of the parameters on the command line:

 

ls /sys/bus/iio/devices/iio:device0

 

Parameters can be read with cat, for example the "name" parameter:

 

cat /sys/bus/iio/devices/iio:device0/name

 

In this example, the “name” parameter would be accel_3d for the 3D Accelerometer and gyro_3d for the 3D Gyroscope.

 

Single-shot sensor readout in Linux

 

Single-shot readout (in this example, the Z axis):

 

cat /sys/bus/iio/devices/iio:device0/in_accel_z_raw

cat /sys/bus/iio/devices/iio:device0/in_anglvel_z_raw

 

Note that the reported parameters have different names, depending on if you’re using an accelerometer or a gyroscope.

 

They are scaled to standard units (m/s² and rad/s) with the following parameters:

 

cat /sys/bus/iio/devices/iio:device0/in_accel_scale

cat /sys/bus/iio/devices/iio:device0/in_anglvel_scale

 

Continuous stream

 

To use the maximum frequency, it’s better to use a continuous buffer stream rather than trying to over-sample with too many single-shot reads. If the goal is to integrate the IIO data closely with an application, the library libiio is a good choice.

 

The tool iio-readdev is also useful, it's located in the libiio-utils package.

 

Install iio-readdev with apt (available in Ubuntu repositories, for example):

 

sudo apt-get install libiio libiio-utils

 

Lingon Electronics also offers a Python script for easy interpretation of the raw data into a human readable CSV-friendly format.

 

https://github.com/lingon-electronics/iio-scripts/

 

sudo python iio_stream_capture.py

sudo python iio_stream_capture.py > measurement.csv

 

The script will run continuously and fill the table with new values until stopped (stop with CTRL-C if run from terminal), so make sure to end it when the measurement is complete.

 

Feel free to modify the script according to your needs. Note that the script needs root privilegies due to usage of iio-readdev. Single-shot readout is however normally available without usage of sudo.

 

Further reading

 

Linux Device Drivers Development by John Madieu (2017) has a chapter with a good introduction to the IIO subsystem, included in modern distributions of Linux.

 

Version compatibility

 

The IIO subsystem has existed in mainstream Linux distributions for many years. If your device is enumerated as a generic HID (hidraw) instead of IIO, then you're either using a very old kernel or some experimental lightweight version with reduced functionalities.

Windows

 

Support for the HID sensor standard is included with Windows 10 (and also Windows 8.1). Since the sensors are compatible with the HID protocol, they require no extra drivers to operate. The first time they’re connected, there might be a delay of a few seconds as Windows starts to initialize its native built-in compatibility with HID sensors.

 

A list of connected sensors can be viewed at “Sensors” in Device Manager.

 

Documentation for developers

Microsoft has gathered documentation for HID sensors on Windows Dev Center. The relevant pages are located at:

https://docs.microsoft.com/en-us/windows/uwp/devices-sensors/sensors

The pages “Use the accelerometer” and “Use the gyrometer” provide a quick way to get started with integrating sensor data to your application.

 

They have also provided some example code on Github:

https://github.com/Microsoft/Windows-universal-samples

 

Sample applications (third-party)

Windows Store has a few applications which can be used to try out connected HID sensors. These have been created by third-party developers independently of us.

 

SensorInfo:

Shows a live chart of connected HID sensor output. It’s a very simple app in terms of complexity, and the update frequency for the chart is unfortunately low, despite higher data output frequency from the connected sensor. It will unfortunately not output the measured data as files, there's only the live graph and nothing else.

 

Classic Marble Maze:

A classical game which accepts input from a connected HID compatible accelerometer, such as the 3D Accelerometer. Note that the sensor has to be connected before starting the game, otherwise it will assume that you’re going to use the keyboard.

 

GyroMaze:

Similar to Classic Marble Maze. Contrary to the title, this game uses data from a connected accelerometer, not gyroscope.

 

 

Other information

 

USB Vendor ID and Product ID

3D Accelerometer: 16d0:0de6

3D Gyroscope: 16d0:0de7

 

Serial number

Every device comes with a serial ID (the iSerial parameter, to be precise) which is presented to the connected computer over the USB interface. It should be treated like a text string, since it's an ASCII representation of a number in hexadecimal. This feature offers the possibility to perform calibrations and verifications of individual units. Note that there is no storage for calibration parameters inside the products, they should be handled externally if needed.

 

Desktop auto-rotation

The 3D Accelerometer is compatible with the auto-rotation feature in some Linux desktops (tested on Ubuntu 19.04).


It might be necessary to start the computer with the accelerometer plugged in (depends on which distro you're using). The recommended position is a USB connector on the right side. If your desktop does not support auto-rotation, and you still want to experiment, you can try making your own scripts.

 

Here's some inspiration for Linux users:

https://linuxappfinder.com/blog/auto_screen_rotation_in_ubuntu

https://unix.stackexchange.com/questions/410826/change-iio-sensors-data-via-custom-accel-mount-matrix/

 

And for Windows users:

https://stackoverflow.com/questions/39288135/rotating-the-display-programmatically

 

CONTACT US

Lingon Electronics AB

Åkerbyvägen 82

183 35 Täby

Sweden

© Lingon Electronics, 2019