Consensys User Guide

1. Introduction

Consensys is Shimmer’s Windows application for working with Shimmer3 and Shimmer3R units. With it you can program a Shimmer’s firmware, configure it, log data to its SD card or stream data over Bluetooth, see the data as it arrives, and keep, process and export the recordings.

Note: Some of the screenshots in this guide come from earlier versions of Consensys, and show a Shimmer3 or a Consensys Base6. The current version’s screens may look slightly different, and a Shimmer3R is configured the same way.

1.1. What you need

• Software: ConsensysBASIC or ConsensysPRO (Section 1.2), from the Shimmer website.
• Hardware: a Shimmer Dock, Consensys Base6 or Consensys Base15, and any Shimmer3 or Shimmer3R units. A Shimmer3R can also connect directly over USB-C (Section 6.4).
• Firmware: LogAndStream on every Shimmer. Consensys installs it (Chapter 5).
• For streaming: a PC with Bluetooth.

1.2. ConsensysBASIC and ConsensysPRO

Consensys comes in two editions, chosen when it starts:

• ConsensysBASIC is free, and works with one Shimmer at a time.
• ConsensysPRO works with many Shimmers at once, and adds event markers, processing of recorded data (filters and algorithms), advanced plotting and more. It needs a licence; you can try it free for 5 days (Chapter 3).

Where a feature is ConsensysPRO only, this guide says so.

1.3. What’s new in Consensys 2

• 2.0: Shimmer3R support; sensor calibration built in (Chapter 8); Lab Streaming Layer and keyboard support (Chapter 9). The SDLog firmware is no longer supported: its features are now part of LogAndStream.
• 2.2: Shimmer3R over USB-C (Section 6.4).

2. Installing

These steps install Consensys, and the drivers for a Shimmer Dock or Consensys Base.

2.1. Connecting the Dock or Base

1. Download Consensys from the Shimmer website.
2. Take any Shimmers out of the Base or Dock; dock them only when the drivers have installed.
3. Connect the AC adapter to the Base, and plug it into a mains socket. (A Shimmer Dock is powered over USB.)
4. Connect the Base or Dock to the PC with its USB cable.
5. Windows installs the drivers. Its progress shows in the notification area at the bottom right of the screen, and can take a few minutes. If you are not sure it has finished, go on to check it in the next section.

2.2. Checking the drivers

1. Open the Device Manager: press Windows key + R, type devmgmt.msc and click OK.

2. Expand Universal Serial Bus controllers. A Shimmer Dock adds two USB Serial Converter entries; a Base6 or Base15 adds four.

   

3. For each USB Serial Converter, right-click it and choose Properties:

   • on the Driver tab, check that the FTDI driver is version 2.12.0.0 or later;
   • on the Advanced tab, check that Load VCP is ticked.

   

If every converter has the right driver, go on to Section 2.4. If not, install the driver by hand first (Section 2.3).

2.3. Installing the FTDI driver by hand

1. Download the latest Windows setup executable of the VCP driver from FTDI: https://ftdichip.com/drivers/vcp-drivers/.
2. Right-click the downloaded file and choose Run as administrator. Click Yes if Windows asks for permission, and Run if a security warning appears.
3. Click Extract, then Next; accept the licence and click Next.
4. When the drivers have installed, click Finish, then Restart Now.
5. Check the drivers again (Section 2.2) before going on.

2.4. Installing Consensys

1. Extract the zip file you downloaded.
2. Double-click setup.exe and follow the installer’s instructions.
3. When it has finished, start Consensys from its desktop icon.

3. Licensing ConsensysPRO

ConsensysPRO needs a licence. Skip this chapter if you use only ConsensysBASIC, which needs none.

3.1. Licence types

• Subscription: ConsensysPRO for a set period, renewed every year (365 days).
• Floating: a number of activations that can be in use at the same time. Consensys counts the running copies, and no more can run at once than the licences allow.
• Trial: ConsensysPRO free for 5 days. After that, buy a licence or carry on with ConsensysBASIC.

Licences can be bought from the Shimmer website.

3.2. Activating a licence

Activate ConsensysPRO when Consensys starts, or later from Help → Upgrade to PRO.

3.3. Managing licences

Help → Manage Licenses shows the licensee and licence details. Deactivating the licence on a computer frees that activation for another one: in the Licensee Activations panel on the right, click the X beside the PC to deactivate. You can deactivate only the computer you are working on.

4. The Consensys Workspace

The first time a new version of Consensys runs, it asks where to create its workspace, the folder that holds its files. Click OK to use the recommended default.

The workspace holds:

Table 4‑1 Workspace folders

To open the workspace folder, choose Application Settings and click Open.

5. Programming Firmware

Shimmers must run LogAndStream firmware to work with Consensys. To program it:

1. Start Consensys and click MANAGE DEVICES.

   

2. Switch the Shimmers on and place them in the Base or Dock.

3. Select the Shimmers, by clicking them in the picture of the Base or in the device list, and click FIRMWARE.

   

4. Choose the firmware file and click PROGRAM. Click DONE when it has finished.

   

Shimmer3R: a Shimmer3R can also be programmed over USB-C (Section 6.4).

5.1. Reload configuration after firmware write

The firmware dialog’s Reload configuration after firmware write option decides what happens to the Shimmer’s configuration and calibration:

• Ticked (the default): after programming, Consensys writes the Shimmer’s previous configuration back, calibration included. When the Shimmer is next undocked, it reloads its calibration from the calibration file on its SD card. Nothing needs to be set up again.
• Unticked: Consensys resets the configuration and the calibration to their defaults, on the Shimmer and on its SD card. Configure the Shimmer again, and calibrate it again (Calibrating the Sensors in the IMU User Guide).

Untick it only to return a Shimmer to its factory settings, for example to recover one that misbehaves (Section 12.2). The data files on the SD card are not touched either way.

6. Logging to the SD Card

A Shimmer can log its data to its SD card, with no PC nearby; afterwards Consensys imports the data from the card. This chapter uses the SD Log with Inter-device Sync recording option, which also keeps several Shimmers in step with each other (see Synchronised logging in the Shimmer3/3R User Manual).

6.1. Configuring the trial

1. In MANAGE DEVICES, select one or more Shimmers with the same firmware (type and version), and click CONFIGURE. (ConsensysBASIC: one Shimmer.)

   

2. Trial details: choose a Trial Name, select SD Log with Inter-device Sync, and set Auto Stop in minutes, or 0 for no set length.

   

3. Starting and stopping: choose whether logging starts and stops with the User Button (used in this guide) or by undocking and docking. Log for at least a minute, so that a data file is written.

   

4. Each Shimmer: choose its Shimmer Name and Sampling Rate, and click the sensor tiles to enable and set up the sensors.

   

5. Algorithms (ConsensysPRO): enable the algorithms for each Shimmer’s hardware, such as 9DoF to Quaternion on an IMU or ECG to Heart Rate on an ECG unit.

   

6. Calibration: check each Shimmer’s IMU calibration on the Calibration tab. The reset buttons return all the IMU sensors, or one of them, to the factory defaults. A Shimmer shown with a red warning symbol has an invalid IMU calibration: reset it to the defaults, or calibrate it (Chapter 8).

   

7. Click WRITE CONFIG to save the configuration (trial, Shimmer, sensor, algorithm and calibration settings) to every Shimmer. Wait until it has been written, then click NEXT.

   

6.2. Logging

1. Take the Shimmers out of the Base or Dock. Do not switch them off.
2. Press the orange user button on each Shimmer to start logging. The green LED flashes on and off once a second while it logs.
3. Press the button again to stop. The upper LED then blips briefly once every two seconds: blue, or green if Bluetooth is disabled in the configuration (see LED indicators).

6.3. Importing the data

1. Scan the SD cards: put the Shimmers in the Base, select them, and click IMPORT. Click NEXT when scanning has finished.

   

2. Choose what to import: select data from one or more Shimmers, and add it as a new session to the list on the right. Each trial’s sessions are numbered: New Session:1, New Session:2 and so on.

   

3. Choose what to delete: select the data you do not want to import, and mark it Delete Only. Click NEXT, and YES to confirm.

   

4. Import: the selected data is imported into the database, and the marked data deleted from the cards. Click DONE to go to MANAGE DATA (Chapter 10).

   

6.4. Shimmer3R over USB-C

A Shimmer3R with LogAndStream v1.00.58 or later can be connected to the PC with a USB-C cable instead of a Base or Dock. It then appears in MANAGE DEVICES: click its picture to select it, and you can program its firmware (Chapter 5) and configure and import its logging (this chapter) as you would in a Base.

7. Streaming over Bluetooth

A Shimmer can stream its data to the PC over Bluetooth, where Consensys plots it and can record it. The PC needs Bluetooth.

7.1. Pairing

Pair each Shimmer with Windows once: Settings → Bluetooth & devices → Add device → Bluetooth.

Consensys uses Bluetooth Classic, not Bluetooth Low Energy (BLE). Pair the Classic entry, named Shimmer3-XXXX or Shimmer3R-XXXX-BT, where XXXX is the end of the Shimmer’s Bluetooth address. If Windows asks for a PIN, enter 1234: a Shimmer3 asks for it, and so does a Shimmer3R in SD-sync mode. A Shimmer3R otherwise needs none.

Note: do not pair the BLE entry (S3BLE-XXXX or Shimmer3R-XXXX-BLE). If a Shimmer has been paired both ways, remove both pairings and pair the Classic entry again.

7.2. Connecting

1. Open LIVE DATA.

   

2. Every Shimmer paired with the PC is listed under Available Devices. (ConsensysBASIC: one Shimmer at a time.)

   

3. Click the connect button beside a Shimmer. Shimmers you have connected before are shown with a picture, which also shows whether they are docked.

   

4. Connect to more Shimmers the same way. Connected Shimmers move to the top of the list.

   

7.3. Configuring

1. Select Shimmers: click their icons, or right-click SELECT and choose Select All. Selecting enables the buttons for the group: connect, configure, start streaming and record. The buttons on each row act on that Shimmer only.

   

2. Click Configure. Shimmers configured together belong to the same trial, shown by the same colour; Shimmers in different trials have different colours.

   

3. Choose the Trial Name and Auto Stop (0 for no set length). How logging starts and stops cannot be changed over Bluetooth; change it in MANAGE DEVICES if you need to.

   

4. For each Shimmer, choose its Shimmer Name and Sampling Rate, and click the sensor tiles to enable and set up the sensors. Then click WRITE CONFIG, wait until it has been written, and click NEXT.

   

7.4. Streaming and plotting

1. Take the Shimmers out of the Base or Dock.

   

2. Choose the signals to plot, and click START to start streaming. Each plot can show several signals from several Shimmers. Device properties, such as the battery voltage, can be plotted but are not recorded.

   

3. Right-click a plot to change its settings, such as the data format. The plot options also add plots, and pop a plot out of the main window or back in.

   

7.5. Recording

1. On the RECORD tab, click START TO PC to record the stream to the PC. (START TO SD starts the Shimmers of the same trial logging to their SD cards.)

   

2. If the selected Shimmers belong to more than one trial, choose the trial to record and click CONFIRM.

3. Click STOP TO PC to stop. Each recording is added to the trial as a new session.

   

To record to the SD cards and the PC at the same time, start streaming, start recording to SD (streaming pauses briefly), then start recording to the PC. Recordings to SD are imported afterwards (Section 6.3).

7.6. Event markers

ConsensysPRO only. Event markers mark moments during a recording, such as a stimulus or a fall. They are created, and used, while at least one Shimmer is connected over Bluetooth.

1. Create markers: slide out the event marker panel, and create markers of type Pulse or Toggle. Existing markers can be edited or deleted there.

   

2. Mark events: press a marker’s button when the event happens. The marker is plotted, with a value that identifies which marker it was.

   

3. Apply them: click APPLY to attach the markers to their datasets, so that they are exported with the sensor data.

   

8. Calibrating the Sensors

Consensys calibrates the Shimmer’s accelerometers, gyroscope and magnetometer. Configure the Shimmer with the sensors you want to calibrate enabled and a sampling rate of 51.20 Hz, and start streaming: the Calibration button becomes available. Each sensor’s tab works only while that sensor is enabled and the rate is 51.20 Hz.

Choose the sensor, follow the steps shown, and save the new calibration to the Shimmer. The panel shows the new parameters beside those already saved on the Shimmer.

What each step asks you to do, and how to check the result, is described in Calibrating the Sensors in the IMU User Guide.

9. Keyboard and Lab Streaming Layer

Keyboard: a keyboard can be added as a device. Its keys can then mark events while recording, and its keystrokes can be streamed over Lab Streaming Layer.

Lab Streaming Layer (LSL): Consensys can stream to Lab Streaming Layer, for recording alongside other LSL devices. Enable it in the settings. Its offset allows for latency: Bluetooth latency is typically about 25 ms and can reach about 100 ms (Bluetooth latency in the Shimmer3/3R User Manual), and an offset of 100 ms sets each sample’s LSL time to lsl_clock() - 0.1 s.

10. Managing Data

MANAGE DATA holds everything Consensys has recorded: SD recordings, imported from Shimmer SD cards (Section 6.3), and PC recordings, streamed and recorded over Bluetooth (Section 7.5).

10.1. The data list

Data is listed by trial, then session, then Shimmer. For a trial logged with SD Log with Inter-device Sync, M marks the master Shimmer, and green ticks in the SYNC column show that the Shimmers’ data was aligned successfully. Data descriptions (ConsensysPRO only) hold notes on each trial and session.

10.2. Exporting

1. Select one or more sessions from one trial, and click EXPORT.

2. Choose the File Delimiter, File Format, Timestamp Format and Data Format, and click OK.

   

3. When the export has finished, click OPEN PATH to find the files. They open in a spreadsheet, or in tools such as MATLAB.

   

10.3. Deleting

1. Select the data to delete, click DELETE, and click YES to confirm.

   

2. Click DONE when it has finished. The data no longer appears in the list.

10.4. Processing

ConsensysPRO only. Recorded signals can be filtered, or run through algorithms, and the results added to the session.

1. Select the signals to process, for example an ECG lead, and click PROCESS.

   

2. Choose Filters or Algorithms; only the algorithms suited to the selected signals are offered. A filter step applies one filter; to apply another, process the result again. Click NEXT.

3. Select the signals, set the filter’s parameters, add them to PROCESSED SIGNALS OUT, and click Apply.

   

4. Click DONE when processing has finished. The processed signal, here ECG_LA_RA_24BIT_HPF, is added to the session.

   

10.5. What an exported file contains

An export writes one file for each Shimmer in each selected session, into a new folder. This section describes those files: their names, their header rows, the timestamp column and the column for each sensor.

10.5.1. Export options

Table 10‑1 Export options

10.5.2. Folder and file names

Folder: each export creates a folder named after the trial and the sessions exported, for example 2026-10-08_14.22.05_GaitStudy_SD_Session3. It starts with the date and time the trial was configured; it ends with _SD (SD recording) or _PC (PC recording) and the session, or with _MultiSession when more than one session is exported. Consensys will not export into a folder that already exists: move or rename the earlier export first.

Files: one file per Shimmer per session, named

<Trial>_Session<N>_<Shimmer name>_<Calibrated|Uncalibrated>_<SD|PC>.<format>

for example GaitStudy_Session3_Shimmer_86F8_Calibrated_SD.csv. If a participant ID is recorded for that Shimmer and session, it comes first, followed by a full stop. When a file chunk size is set, every file gets a part number, _001, _002 and so on, before the extension, and each part starts with the full header rows.

Data Descriptions.txt (ConsensysPRO only) is written beside the data files. It holds the trial’s time zone and UTC offset, the trial and session descriptions, and, for each session, the event markers used: their code, how many times each was used, name and description.

10.5.3. Text files (.csv, .dat, .txt)

A text file has three header rows, then one row per sample:

1. "sep=," (or the tab or semicolon chosen). This tells Microsoft Excel which delimiter the file uses, so the file opens in columns. Other programs may need to skip this row.
2. The column names.
3. The units of each column.

For example, the start of a calibrated, tab-delimited export from a Shimmer3R GSR+ Unit (tabs shown as spaces, columns trimmed):

"sep=   "
Shimmer_86F8_Timestamp_Unix_CAL  Shimmer_86F8_LIS2DW12_ACC_X_CAL  ...  Shimmer_86F8_GSR_Skin_Conductance_CAL  Shimmer_86F8_GSR_Skin_Resistance_CAL  Shimmer_86F8_PPG_A1_CAL  Shimmer_86F8_BMP390_Pressure_CAL
ms                               m/(s^2)                          ...  uS                                     kOhms                                 mV                       kPa
1.7897147642417297E12            1.0149611011370436               ...  125.0                                  8.0                                   0.7326007326007326       100.83801757275134

• Column names are <Shimmer name>_<channel>_<CAL|UNCAL>. The timestamp column is always _CAL, even in an uncalibrated export.
• The first column is the timestamp. Then come the channels selected for export, and the event marker column, if any, is always last.
• Every row ends with a delimiter, so some programs show an extra, empty column at the end.
• Numbers are written at full precision, and large numbers in scientific notation: 1.7897147642417297E12 is 1 789 714 764 241.7297 ms. Spreadsheets and MATLAB read this form.
• A missing value is written as -1, for example a heart-rate column before the algorithm has found a beat.

10.5.4. MATLAB files

A .mat file holds one variable per column, each a column of numbers (double), named like the text file’s column names but with every - changed to _, for example Shimmer_86F8_ECG_LL_RA_24BIT_CAL. A .mat file has no units and no sep row; the units are those of the text export in Table 10‑2 and Table 10‑3. The timestamp variable is always _CAL. Formatted Local timestamps are not available in a .mat file.

10.5.5. The timestamp column

The first column is the timestamp, in the format chosen with Timestamp Format (Table 10‑1). Consensys offers three formats. The default, Unix, gives each sample’s time in milliseconds since 1 January 1970 (UTC). Every format’s timestamps are in milliseconds, except Formatted Local, which is a date and time.

Table 10‑2 Timestamp formats

• Where Unix time comes from. For an SD recording, it is the Shimmer’s real-time clock, which Consensys sets when the Shimmer is docked (Section 11.1). For a PC recording, it is the Shimmer’s timestamp converted to the PC’s clock where Consensys could do so, otherwise the time at which the PC received the sample.
• TimestampSync marks aligned timestamps. In a trial logged with SD Log with Inter-device Sync, they are the master’s timestamps and the other Shimmers’ once aligned to the master. In a PC recording, they are the Shimmer’s timestamps converted to the PC’s clock. A Shimmer in a synchronised trial that could not be aligned is exported with Timestamp, unaligned, and Consensys says so before the export.
• If the clock was not set (the Shimmer’s LEDs flashed green and blue), there is no Unix time for an SD recording. Consensys warns that the “Shimmer Timestamp will be exported instead”, and the export uses the Shimmer format.
• Formatted Local is the Unix time shown at the UTC offset recorded with the trial (written in Data Descriptions.txt), and so needs the clock set too. The same offset is used for the whole export: it does not change for daylight saving time. If the clock was not set, Consensys gives no warning: a Formatted Local export shows dates on 1 January 1970, counted from the Shimmer’s own clock. Use the Shimmer format, or set the clock before recording.
• The Shimmer format’s units row can read Ticks, but its values are milliseconds, not ticks of the Shimmer’s clock (one tick is 1/32768 s). Read the column as milliseconds whatever its units row says. This affects only the Shimmer format: the default Unix format’s units row reads ms.

10.5.6. Calibrated and uncalibrated data

• Calibrated values are in the units in Table 10‑3, using each sensor’s calibration (Section 8).
• Uncalibrated values are the raw numbers the Shimmer measured: ADC counts for the analogue channels, GSR, PPG and battery; the sensor’s raw reading for the accelerometers, gyroscope, magnetometer and pressure sensor; ExG counts. Their units row reads no_units. Channels that only exist after processing (filters, heart rate, quaternions) have no uncalibrated form and are left out.

10.5.7. Sensor columns

Table 10‑3 gives the <channel> part of each column name. Shimmer3R: most inertial and pressure columns are named after the sensor chip, as the table shows, rather than after the measurement.

Table 10‑3 Sensor columns and calibrated units

The analogue inputs are listed in the same order in both columns: Shimmer3R’s Ext A0 is Shimmer3’s Ext A7, and so on. On Shimmer3R the Int A1 column is named Int_Exp_A1, as on Shimmer3; the other Shimmer3R analogue columns start with F5437a_.

Event markers: the column holds the code of the marker set at that sample. Each marker’s code is a power of two (1, 2, 4, 8 …), listed with its name in Data Descriptions.txt. If several markers are active at a sample, the column holds the sum of their codes: markers 1 and 4 together read 5.

ExG: the column names depend on the ExG configuration chosen (Table 10‑4). Each channel is _24BIT or _16BIT, after the resolution set. Calibrated ExG values are in mV; the status columns ECG_EMG_Status1 and ECG_EMG_Status2 have no_units. The names are the same on Shimmer3 and Shimmer3R.

Table 10‑4 ExG columns

10.5.8. Processed signals

Signals added by PROCESS (Section 10.4) are exported like any other channel, with these names. If a name is already in use in the session, _2, _3 and so on is added.

Table 10‑5 Processed signal columns

Heart rate and beat interval columns read -1 where no value was found. Consensys adds quaternions only; it does not export Euler angles. The 6DoF and 9DoF IMU to quaternion algorithms are for Shimmer3 data only: they are not offered for Shimmer3R recordings.

11. Things You Might Need to Know

11.1. Setting the Shimmer’s clock

If a Shimmer’s upper LED flashes green and blue rapidly, its real-time clock is not set. Place it in a Base or Dock while Consensys is running, and Consensys sets the clock from the PC; the flashing stops. The clock relates the Shimmer’s timestamps to real time, so that its data can be lined up with other Shimmers and other devices. See Real-time clock in the Shimmer3/3R User Manual.

11.2. Opening a Shimmer’s SD card

To open the SD card of a Shimmer in a Base, right-click its picture in MANAGE DEVICES and choose Open SD.

11.3. Importing from the backup

Everything imported from SD cards is also kept in the workspace’s Backup folder (Chapter 4). To import from it again, open the Manage Data category of the Application Settings and click Open the backup, choose the backup folder and click Next. The import continues as in Section 6.3, step 2.

11.4. Help

This guide and the Consensys FAQ are opened from Help → User Guide and Help → FAQ. The manuals for all Shimmer hardware are on the Shimmer documentation pages; new users should start with the Shimmer3/3R User Manual.

11.5. PROTO3 Mini on newer Shimmer3 IMU units

A PROTO3 Mini fitted to a newer Shimmer3 IMU (SR31-7 or later) needs its expansion board ID set in Consensys, so that Consensys recognises it, and set back when the board is removed. The steps are in Assembling the PROTO3 Mini Expansion Board in the PROTO3 Series User Guide.

12. Troubleshooting

12.1. Dock and Base problems

Check the relevant sections of this guide and the Consensys FAQ first. If that does not solve it, contact us through our contact page, and include the contents of the workspace’s App Logs folder.

12.2. Recovering a Shimmer

If a Shimmer behaves oddly or locks up when it starts, reprogram its firmware (Chapter 5) with Reload configuration after firmware write unticked. This returns it to its factory default settings, and resets its calibration too: calibrate it again afterwards (Section 5.1).

12.3. Problems with recorded data

Check this guide and the Consensys FAQ first. If the problem remains, contact us through our contact page, and include the trial’s database file and, for data imported from SD cards, its backup:

• Find the database file: hover over the trial in MANAGE DATA. Its database file name, ten digits followed by .db such as 1435243126.db, is shown. The number is the time the trial was configured, as a Unix timestamp: 1435243126 is 25 June 2015, 14:38:46 UTC.

  

• Find the files: open the workspace (Application Settings, then Open). The Database folder holds a folder for each trial, named by that number. The Backup folder holds the binary files copied from the SD cards, by import date; it is not used for data recorded over Bluetooth. Zip the folder for the import date to send it.

  

12.4. Running out of disk space

A lot of recorded data can fill the PC’s disk. To archive trials you no longer need in Consensys:

1. In MANAGE DATA, find each trial’s database name (Section 12.3).
2. In the workspace’s Database folder, find the folder of the same name, and check that it holds a .db file.
3. Move the folder, without renaming it, to safe storage such as an external disk. Restart Consensys: the trial no longer appears in MANAGE DATA.
4. Keep a note of each archived trial: its name, its database name and what study it belongs to.

To see an archived trial again, copy its folder back into the Database folder and restart Consensys.