Preview: this manual is being updated to cover Shimmer3R. Notes marked TODO are open questions our team is still confirming.
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.
TODO(S3R): Many of the screenshots in this guide come from earlier versions of Consensys (some from 1.0.5) and from a Consensys Base6. Replace them with screenshots of the current version, with a Shimmer3R where it differs.
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.
Figure 1‑1 Choosing ConsensysBASIC, activating ConsensysPRO, or trying ConsensysPRO
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
- Download Consensys from the Shimmer website.
- Connect the AC adapter to the Base, and plug it into a mains socket. (A Shimmer Dock is powered over USB.)
- Connect the Base or Dock to the PC with its USB cable.
- 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.
Figure 2‑1 Windows installing the drivers for the Base
2.2. Checking the drivers
Open the Device Manager: press Windows key + R, type
devmgmt.mscand click OK.Expand Universal Serial Bus controllers. A Shimmer Dock adds two USB Serial Converter entries; a Base6 or Base15 adds four.
Figure 2‑2 USB Serial Converters in the Device Manager
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.
Figure 2‑3 The FTDI driver version, on the Driver tab
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
- Download the latest Windows setup executable of the VCP driver from FTDI: https://ftdichip.com/drivers/vcp-drivers/.
- Right-click the downloaded file and choose Run as administrator. Click Yes if Windows asks for permission, and Run if a security warning appears.
- Click Extract, then Next; accept the licence and click Next.
- When the drivers have installed, click Finish, then Restart Now.
- Check the drivers again (Section 2.2) before going on.
Figure 2‑4 The FTDI driver installer
2.4. Installing Consensys
- Extract the zip file you downloaded.
- Double-click
setup.exeand follow the installer’s instructions. - 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.
Figure 3‑1 Activating ConsensysPRO 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; you can deactivate only the computer you are working on.
Figure 3‑2 Help → Manage Licenses
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.
Figure 4‑1 Creating the workspace
The workspace holds:
| Folder | Contents |
|---|---|
| App Logs | Debug logs. Include them with a support request about the Dock, Base or software |
| Backup | A copy of everything imported from Shimmer SD cards |
| Database | The recordings: data imported from SD cards and recorded over Bluetooth, one database per trial |
| Documentation | This guide and the FAQ, also opened from the Help menu |
| Firmware | Shimmer3 and Shimmer3R firmware, for programming Shimmers |
| Default Trial | Created when a Verisense or wrist sensor (experimental) is synced: its binary and parsed (e.g. CSV) files |
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:
Start Consensys and click MANAGE DEVICES.
Figure 5‑1 MANAGE DEVICES
Switch the Shimmers on and place them in the Base or Dock.
Select the Shimmers, by clicking them in the picture of the Base or in the device list, and click FIRMWARE.
Figure 5‑2 Selecting Shimmers in MANAGE DEVICES
Choose the firmware file and click PROGRAM. Click DONE when it has finished.
Figure 5‑3 Choosing the firmware to program
Shimmer3R: a Shimmer3R can also be programmed over USB-C (Section 6.4).
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 Shimmer User Manual).
6.1. Configuring the trial
In MANAGE DEVICES, select one or more Shimmers with the same firmware (type and version), and click CONFIGURE. (ConsensysBASIC: one Shimmer.)
Figure 6‑1 Selecting Shimmers to configure
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.
Figure 6‑2 Trial details
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.
Figure 6‑3 How logging starts and stops
Each Shimmer: choose its Shimmer Name and Sampling Rate, and click the sensor tiles to enable and set up the sensors.
Figure 6‑4 Shimmer name, sampling rate and sensors
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.
Figure 6‑5 Algorithms
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).
Figure 6‑6 Reviewing calibration
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.
Figure 6‑7 Writing the configuration
6.2. Logging
- Take the Shimmers out of the Base or Dock. Do not switch them off.
- Press the orange user button on each Shimmer to start logging. The green LED flashes on and off once a second while it logs.
- Press the button again to stop. The green LED then blinks briefly once every two seconds.
Figure 6‑8 Undock, leave switched on, press the button; the green LED flashes while logging
6.3. Importing the data
Scan the SD cards: put the Shimmers in the Base, select them, and click IMPORT. Click NEXT when scanning has finished.
Figure 6‑9 Scanning the SD cards
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.
Figure 6‑10 Data added as a new session
Choose what to delete: select the data you do not want to import, and mark it Delete Only. Click NEXT, and YES to confirm.
Figure 6‑11 Data marked “Delete Only”
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).
Figure 6‑12 Import complete
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.
Figure 6‑13 A Shimmer3R connected over USB-C, in MANAGE DEVICES
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. No pairing PIN is needed.
Figure 7‑1 Pairing a Shimmer in Windows
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
Open LIVE DATA.
Figure 7‑2 LIVE DATA
Every Shimmer paired with the PC is listed under Available Devices. (ConsensysBASIC: one Shimmer at a time.)
Figure 7‑3 Paired Shimmers in LIVE DATA
Click the connect button beside a Shimmer. Shimmers you have connected before are shown with a picture, which also shows whether they are docked.
Figure 7‑4 Connecting to a Shimmer
Connect to more Shimmers the same way. Connected Shimmers move to the top of the list.
Figure 7‑5 Two connected Shimmers
7.3. Configuring
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.
Figure 7‑6 Selected Shimmers and the group buttons
Click Configure. Shimmers configured together belong to the same trial, shown by the same colour; Shimmers in different trials have different colours.
Figure 7‑7 Configuring connected Shimmers
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.
Figure 7‑8 Trial name and auto stop
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.
Figure 7‑9 Shimmer settings, sensors and WRITE CONFIG
7.4. Streaming and plotting
Take the Shimmers out of the Base or Dock.
Figure 7‑10 Undocked Shimmers ready to stream
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.
Figure 7‑11 Choosing signals and starting the stream
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.
Figure 7‑12 Plot settings
7.5. Recording
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.)
Figure 7‑13 The RECORD tab
If the selected Shimmers belong to more than one trial, choose the trial to record and click CONFIRM.
Click STOP TO PC to stop. Each recording is added to the trial as a new session.
Figure 7‑14 Recording to the PC
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.
Create markers: slide out the event marker panel, and create markers of type Pulse or Toggle. Existing markers can be edited or deleted there.
Figure 7‑15 Creating event markers
Mark events: press a marker’s button when the event happens. The marker is plotted, with a value that identifies which marker it was.
Figure 7‑16 Event marker buttons and their plot
Apply them: click APPLY to attach the markers to their datasets, so that they are exported with the sensor data.
Figure 7‑17 Applying event markers
8. Calibrating the Sensors
Consensys calibrates the Shimmer’s accelerometers, gyroscope and magnetometer. Stream the low noise accelerometer, wide range accelerometer, gyroscope and magnetometer at 51.2 Hz, and the Calibration button becomes available.
Figure 8‑1 The Calibration button
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.
Figure 8‑2 Calibrating a sensor
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.
Figure 9‑1 Adding a keyboard
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 100 ms, and an offset of 100 ms sets each sample’s LSL time to lsl_clock() - 0.1 s.
Figure 9‑2 Lab Streaming Layer settings
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.
Figure 10‑1 MANAGE DATA
10.2. Exporting
Select one or more sessions from one trial, and click EXPORT.
Choose the File Delimiter, File Format, Timestamp Format and Data Format, and click OK.
Figure 10‑2 Export options
When the export has finished, click OPEN PATH to find the files. They open in a spreadsheet, or in tools such as MATLAB.
Figure 10‑3 Export complete
10.3. Deleting
Select the data to delete, click DELETE, and click YES to confirm.
Figure 10‑4 Deleting data
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.
Select the signals to process, for example an ECG lead, and click PROCESS.
Figure 10‑5 Choosing signals to process
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.
Select the signals, set the filter’s parameters, add them to PROCESSED SIGNALS OUT, and click Apply.
Figure 10‑6 Setting up the processing
Click DONE when processing has finished. The processed signal, here ECG_LA_RA_24BIT_HPF, is added to the session.
Figure 10‑7 The processed signal added to the session
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 Shimmer 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.
Figure 11‑1 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.
Figure 11‑2 Importing from the backup
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 Shimmer 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 the expansion board ID set, so that Consensys recognises it:
- Fit the PROTO3 Mini as the PROTO3 Series User Guide describes.
- Dock the Shimmer and program it with LogAndStream (v0.10.0 or later).
- Hold Ctrl+Alt+Shift and right-click the Shimmer’s picture in the Base or Dock (Consensys 1.5.0 or later).
- Choose Program Exp. (Expansion) Board ID, select Proto3 Mini (SR36), enter revision 2, and click OK.
When the PROTO3 Mini is removed, repeat this choosing Shimmer3 (SR31) and revision 7.
Figure 11‑3 Program Exp. Board ID
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.
Figure 12‑1 Reprogramming without reloading the configuration
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
.dbsuch as1435243126.db, is shown. The number is the time the trial was configured, as a Unix timestamp:1435243126is 25 June 2015, 14:38:46 UTC.
Figure 12‑2 A trial’s database file name
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.
Figure 12‑3 The workspace’s Database and Backup folders
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:
- In MANAGE DATA, find each trial’s database name (Section 12.3).
- In the workspace’s Database folder, find the folder of the same name, and check that it holds a
.dbfile. - Move the folder, without renaming it, to safe storage such as an external disk. Restart Consensys: the trial no longer appears in MANAGE DATA.
- 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.
Legal notices
Legal Notices and Disclaimer
Redistribution IS permitted provided that the following conditions are met:
Redistributions must retain the copyright notice, and the following disclaimer. Redistributions in electronic form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the document.
Neither the name of Shimmer Research, or Realtime Technologies Ltd. nor the names of its contributors may be used to endorse or promote products derived from this document without specific prior written permission.
THIS DOCUMENT IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
