Software

Write your own software for the Attys!

AttysScope (Android)

AttysScope an Android app for the Attys which displays, analyses, records and allows in-app-sharing of data, for example on google drive.

Features

  • DC and mains interference removal
  • Displays signals from V down to uV, resistance and temperature (via a PTC)
  • Add your own realtime displays / processing to it by using Android fragments
  • Saves both filtered and raw signals in a data format which can easily be processed in Python, MATLAB(tm), OCTAVE or R
  • Displays peak to peak voltage, root mean square and heartrate as both plots or just text overlay
  • Fourier spectrum of the signal

Running AttysScope

  1. Pair your phone/tablet with the Attys. In older Android versions you might need to type in a security code which is ‘1234’.
  2. Start AttysScope
  3. Set the gain: for small signals such biosignals (ECG, EMG or EEG) set the gain to x500 or x1000.
  4. Enable the DC removal/highpass filter: many signals (ECG, EMG or EEG) have a DC shift which needs to be removed. The cutuff of the highpass can be set in the preferences. Set it to 10Hz for EMG and for any other signal to 0.1Hz.
  5. Enable the mains filter: biosignals are often contaminated by 50/60Hz mains interference. With this filter you can remove this unwanted component. You can set the notch frequency in the preferences.
  6. Record your data in Python/MATLAB friendly format.

Data format

AttysScope saves data as tab separated values where every column of a tsv file represents a channel:

Column number:

  1. Timestamp in secs (from the moment REC is pressed)
  2. Acceleration X in m/s^2
  3. Acceleration Y in m/s^2
  4. Acceleration Z in m/s^2
  5. Magnetic field X in T
  6. Magnetic field Y in T
  7. Magnetic field Z in T
  8. Analogue channel 1 (unfiltered) in V
  9. Analogue channel 2 (unfiltered) in V
  10. Analogue channel 1 (filtered) in V
  11. Analogue channel 2 (filtered) in V

For example if you want to work with the 1st analogue channel then you extract column #8.

This data format is accepted by python, MATLAB(tm), OCTAVE, GNUPLOT and many other plotting applications.

Python scripts

The data files can directly be loaded into Python. Check out the github repository for an example script and you’ll see how easy it is to process data with python.

How to install

You can also install from source by compiling it with Android Studio.

attys-scope (Windows/Linux)

Features

Records from multiple Attys at the same time

Tested BT dongles which work with more than one Attys (Windows):
  • ASUS-BT400: four Attys
  • Belkin: two Attys

Realtime Python add ons

…to visualise data or feed the data into any other program via UDP. Below is a screenshot where the Fourier Spectrum is calculated with a Python script in realtime:

Here attys-scope talks to the UNREAL engine:

Check out the python folder on github for example scripts such as:

  • Fourier spectrum
  • Amplitude bargraph
  • Heartrate
  • Temperature measurement with a thermocouple
  • Talking to the UNREAL gaming engine

Realtime filtering

attys-scope offers highpass, lowpass, 50/60Hz bandstop filters and an amplitude detector. Feed these signals then into Python or save them for later processing as tsv files.

Windows installation

Installer

Download attys_scope_installer.msi and double click on it.

Compile from source

You can also install from source by compiling it with the (free) Visual Studio C++ community edition or under Linux with QT5-dev installed.

Supported dongles

We recommend the Belkin USB bluetooth dongle, the ASUS-BT400 or internal laptop bluetooth adapters for optimal performance.

Linux installation

Ubuntu packages for xenial and bionic

Add the following two repositories to your Ubuntu system:

sudo add-apt-repository ppa:berndporr/usbdux
sudo add-apt-repository ppa:berndporr/attys

Then select attys-scope.

Installation from source

Check out the source from github and follow the installation instructions in the README.

Supported bluetooth dongles

We recommend the ASUS-BT400 for Linux and in general bluetooth dongles or internal ones based on Broadcom chipsets. The Attys works fine with the Raspberry PI 3 with its integrated bluetooth.

Running attys-scope

  1. Pair your Attys with the computer. This is done in the Windows or Linux settings.
  2. Under Windows start attys-scope by clicking on the icon or type attys-scope under Linux.
  3. Set the gain (x1 – x5000): for small signals such biosignals (ECG, EMG or EEG) set the gain to x1000 or x2000.
  4. Highpass filter (HP): many signals (ECG, EMG or EEG) have a DC shift which needs to be removed. Set it to 10Hz for EMG and for any other signal to 0.1Hz or use the -DC option which removes the DC from a previously measured average.
  5. Lowpass filter (LP): this filter allows you to smooth the incoming signal. It also allows you to smooth the rectified signal, for example if you want to measure the amplitude of the EMG. This is indicated by the || sign.
  6. Bandstop filter (BS): signals are often contaminated by 50/60Hz mains interference. With this filter you can remove this unwanted component.
  7. Record your data in Python/MATLAB friendly format. In general attys-scope saves all unfiltered channels and then in addition the channels which are displayed with all filter operations applied.

Advanced options

  • The ECG mode connects the two positive inputs to each other for Einthoven recordings so that we have a shared electrode. See the howto section for more info.
  • You can switch on a constant current to measure resistance. The current for both channels can be set as well.
  • The Attys has an internal programmable gain amplifier (PGA). By increasing its gain you limit the input range but increase the signal to noise ratio. This might be beneficial for very small signals such as EEG.
  • If you want to process the data in realtime in another application then switch on UDP broadcast. Examples of UDP listeners are on github.

Data format

attys-scope saves data as tab separated values where every column of a tsv file represents a channel:

Column number:

  1. Timestamp in secs (from the moment REC is pressed)
  2. Acceleration X in m/s^2
  3. Acceleration Y in m/s^2
  4. Acceleration Z in m/s^2
  5. Magnetic field X in T
  6. Magnetic field Y in T
  7. Magnetic field Z in T
  8. Analogue channel 1 (unfiltered) in V
  9. Analogue channel 2 (unfiltered) in V
  10. Displayed / filtered channel #1
  11. Displayed / filtered channel #2

For example if you want to work with the 1st analogue channel then you extract column #8. All channels which you watch on screen are saved from column #10, #11, … with all filter operations applied.

This data format is accepted by python, MATLAB(tm), OCTAVE, GNUPLOT and many other plotting applications.

The data packets transmitted via UDP are exactly the same except that the separator is a comma (CSV).

Credits

attys-scope uses QT5.7 under the LGPL. You can download QT5 here.

Google’s Science Journal (Android)

Science Journal is an initiative by google to inspire the next generation of scientists! It’s been widely used in STEM education with more than 100,000 mobile phone / tablet installations.

It allows you to record sensor signals from both the Attys and the internal mobile phone/tablet sensors, document them in an electronic lab book and share the results.

You can configure the Attys to measure Volt, millivolt, microvolt and resistance so that it allows a wide range of experiments, for example in Physics education measuring the voltage induced in a coil, in Chemistry to measure pH or Biology to measure signals such as ECG, EMG, EOG and EEG.

This is the trace shown in the clip above when moving a magnet over an improvised coil to show the induced voltage:

Google science journal talking to ATTYS

How to install

  1. Install AttysScope which contains the driver for ScienceJournal
  2. Install ScienceJournal from google play:

AttysECG (Android)

AttysECG is a specialised ECG program for Attys which displays all frontal leads: Einthoven I,II,II and the augmented leads aVR,aVL,aVF using just 3 electrodes: two on the shoulders/wrists and one on the leg/hip.

Features

Heartrate plot

which allows you to see heartrate variability (HRV) and changes of the heartrate after exercise. It calculates the average BPM, the standard deviation, and the RMSSD.

Heartrate variability

The heartrate variability (HRV) is shown as an animation for biofeedback and breathing exercises.

Vector ECG

The vector ECG is a realtime visual representation of the electrical heart axis not just for R but also for P and T.

PQRST inspector

Pan/zoom into a single PQRST complex and do precise measurements of the timings and amplitudes

Single channel mode

This has been added for Vets or if you just want to record Einthoven II

Heartbeat ‘beep’ sound

This is the classical “beep” sound of a heartrate detector.

Customisable

Add your own realtime displays / processing to it by using Android fragments

Electrode placement

You need three electrodes:

  1. right arm: “-” connected to Channel 1
  2. left arm: “GND”
  3. left leg: “+” connected to Channel 1.

Data format

The ECG is saved as a text file containing human readable numbers. You can always check the content with a text editor. Every row corresponds to a moment in time and the columns contain the different channels:
  1. time in secs
  2. Einthoven I (V)
  3. Einthoven II (V)
  4. Einthoven III (V)
  5. Augmented lead aVR (V)
  6. Augmented lead aVL (V)
  7. Augmented lead aVF (V)
  8. heartrate (BPM)

Python

Python can directly load the data files so that you can plot and process the recorded data. Check out the “python” folder on github for an example script which plots all 6 ECG channels.

How to install

Install AttysECG from google play:

You can also install from source by compiling it with Android Studio.

attys-ecg (Windows/Linux)

ECG Plotting / recording app with heartrate detector

Features

  • Displays the Einthoven leads and Attys’s acceleration
  • Heartrate detector
  • Adaptive movement artefact removal with LMS filter using Attys’s acceleration sensor
  • Saves the Einthoven, augmented leads, heartrate and acceleration in a tab separated datafile for processing in Python, R or MATLAB(tm).

Windows installation

Download attys-ecg-installer.msi and double click on it.

Linux installation

Ubuntu packages for xenial and bionic

Add the following two repositories to your Ubuntu system:

sudo add-apt-repository ppa:berndporr/usbdux
sudo add-apt-repository ppa:berndporr/attys

Then select attys-ecg.

Installation from source

Check out the latest version from github.

Running attys-ecg

Make sure that you have paired the Attys with your bluetooth device.

Under Linux type: “./attys-ecg” or click on it under Windows.

Electrode placement

You need three electrodes:

  1. right arm: “-” connected to Channel 1
  2. left arm: “GND”
  3. left leg: “+” connected to Channel 1.

Data format

The ECG is saved as a text file containing human readable numbers. You can always check the content with a text editor. Every row corresponds to a moment in time and the columns contain the different channels:
  1. time in secs
  2. Einthoven I (V)
  3. Einthoven II (V)
  4. Einthoven III (V)
  5. Augmented lead aVR (V)
  6. Augmented lead aVL (V)
  7. Augmented lead aVF (V)
  8. heartrate (BPM)
  9. Acceleration X (m/s^2)
  10. Acceleration Y (m/s^2)
  11. Acceleration Z (m/s^2)

The heartrate is only set at the moment a heartbeat is detected and otherwise it’s zero. The heartrate is the momentary heartrate between two adjacent R peaks and is median filtered. See github for a detailed explanation.

Credits

attys-ecg is based in part on the work of the Qwt project (http://qwt.sf.net).

attys-ecg uses QT5.7 under the LGPL. You can download QT5 here.

AttysEEG (Android)

AttysEEG is our EEG Android app and has especially been designed for displaying and analysing EEG in realtime on your tablet or phone. You can easily extend it by adding so called Android Fragments for your specific analysis needs which then show up on the right hand side of the app.

Features

Realtime EEG plotting of the different EEG bands

It runs on your phone or tablet and plots the alpha, beta, gamma, delta and theta bands.

Histograms

AttysEEG can show you a histogram of the different bands either in microvolts or normalised units.

Auditory evoked potentials

AEPs are repetitive click sounds which are sent through the headphone jack and are then averaged.

Visually evoked potentials

For the VEPs AttysEEG uses a standard inverting chequerboard stimulus.

Beta Ratio and PowerFastSlow

These measures are used to determine the depth of anaesthesia

Open source

AttysEEG can easily be extended or customised.

AttysEEG on github

Dataformat

Every column represents one channel:

  1. time (sec)
  2. raw EEG (V)
  3. filtered EEG with mains and DC removed (V)
  4. delta band, below 4Hz (V)
  5. theta band, 4-8Hz (V)
  6. alpha band, 8-13Hz (V)
  7. beta band, 13-30Hz (V)
  8. gamma band, above 30Hz (V)

These files can directly be loaded into Python (csv.reader or numpy.loadtxt), Octave and MATLAB(tm).

The bands are created by 2nd order low- and highpass Butterworth filters.

How to install

Install AttysEEG from google play:

You can also install from source by compiling it with Android Studio.

attys-ep (Windows/Linux)

Visually evoked potential app for Attys for Windows/Linux. It performs averaging over repetitive stimuli.

  • Visually evoked potentials with a chequerboard stimulus
  • P300 evoked potential with a coloured oddball stimulus

Windows installation

Download attys-ep-release.msi and double click on it.

Linux installation

UBUNTU packages for xenial and bionic

Add the following two repositories to your Ubuntu system:

sudo add-apt-repository ppa:berndporr/usbdux
sudo add-apt-repository ppa:berndporr/attys

Then select attys-ep.

Installation from source

Check out the latest version on github.

Running attys-ep

Make sure that you have paired the Attys with your bluetooth device.

Just type: “./attys-ep” or click on it under Windows.

Credits

attys-ep is based in part on the work of the Qwt project (http://qwt.sf.net).

attys-ep uses QT5.7 under the LGPL. You can download QT5 here.

Writing your own software

Attys API

github hosts the API for JAVA, Python and C++ for both Linux and Windows.

  • Both pre-compiled packages and source
  • For Linux (also Raspberry PI) and Windows
  • Packages for Ubuntu xenial and bionic
  • Python modules for Linux and Windows
  • Easy to use C++, JAVA or Python classes
  • Converts all raw data into physical units
  • Ring buffering of the incoming data
  • Realtime callbacks
  • Scanning for multiple Attys
  • Example programs for all APIs on github
  • All Attys Programs use these APIs which are also on github

For those who want to write the software completely in Python there is also a pure Python API available.

How to talk to the Attys directly?

The Attys communicates with the host via the bluetooth serial port emulation called “rfcomm” which means that it transmits the measured values as text and receives text commands.

  • Data from Attsy to host: either CSV or BASE64
  • Data from the host to the Attys: text commands

These are the text commands you send to the Attys to change its settings. All commands need to be transmitted without any space and are in general in the form single letter, equal sign and a number. If the command has been understood the Attys reports “OK” back. Only the x=1 command (starts sending data) won’t send “OK”. Note that you first need to stop the data transmission with the command x=0 to issue any other command.

  • Stop data transmission: x=0
  • Start data transmission: x=1
  • Sampling rate:
    • 125Hz (base64/CSV): r=0
    • 250Hz (base64): r=1
    • 500Hz (base64): r=2 (experimental)
    • 1kHz (base64): r=3 (experimental)
  • Data format:
    Data is transmitted as unsigned integers. For the ADC converters the conversion is:
    inVolt = (raw_data - 0x800000) / 0x800000 * 2.42 / ADC_GAIN;
    where the ADC_GAIN is set by the a= and b= commands (default is a gain of 6). For the accelerometer and magnetometer the conversion is:
    inphysicalunits = (raw_data - 0x8000) / 0x8000 * fullScaleRange
    where the full scale range for the magnetometer is 4800.0E-6F and the full scale range for the accelerometer is set by the t= command (see below). The default is 16G. The timestamp is 8 bit and wraps around. If samples cannot be transmitted the timestamp might have gaps so that missing samples can be detected. adc_gpio carries in bits zero and one the internal gpio pins. Bit 7 of adc_gpio is set to one if power is connected for charging.
    • CSV data output (default): d=0
      sprintf(tmp,"01,%02x,%04x,%04x,%04x,%04x,%04x,%04x,%04x,%04x,%04x,%l06x,%l06x,%02x",
      timestamp,
      accel_x,accel_y,accel_z,
      mag_x,mag_y,mag_z,
      adc_ch1,adc_ch2,adc_gpio);
    • Base64/binary (recommended for 250Hz): d=1
      struct __attribute__((__packed__)) bin_data_t {
      uint32_t adc_ch1 : 24;
      uint32_t adc_ch2 : 24;

      uint8_t adc_gpio;
      uint8_t timestamp;

      uint16_t accel_x;
      uint16_t accel_y;
      uint16_t accel_z;

      uint16_t mag_x;
      uint16_t mag_y;
      uint16_t mag_z;

      The short version with just the ADCs transmitted is (f=0,d=1):

      struct __attribute__((__packed__)) bin_data_t {
      uint32_t adc_ch1 : 24;
      uint32_t adc_ch2 : 24;

      uint8_t adc_gpio;
      uint8_t timestamp;
  • Send status back to a terminal (for example putty): i=0
  • Master reset: m=0
  • Accelerometer full scale range:
    • 2G: t=0
    • 4G: t=1
    • 8G: t=2
    • 16G: t=3
  • Partial/full data set:
    • Full data set with all channels: f=1
    • ADC data only: f=0
      Note that this has no effect on CSV data.
  • Gain/Multiplxer: this command uses the upper 4 bits (called here ggg) of a byte for the gain and the lower 4 bits to set the multiplexer (called here mmm):
    0ggg0mmm
    The bits ggg set the gain for the ADC at
    0: x6, 1: x1, 2: x2, 3: x3, 4: x4, 5: x8, 6: x12

    Settings for the multiplexer are
    mmm=0 for normal operation, mmm=1 for connection to GND, mmm=4 for the internal temperature sensor and mmm=6 for an internal connection between both analogue “+” inputs for ECG/Einthoven recordings on both channels.

    • Set mux/gain of ADC channel 1: a=0ggg0mmm as a decimal number, for example a=16 sets the gain to 1 because 16=00010000 and a=0 sets the gain to 6.
    • Set mux/gain of ADC channel 2: b=0ggg0mmm as a decimal number.
  • Constant Current: you can switch on a constant current on a channel to measure the resistance against GND. This is useful to determine the electrode resistance or to measure resistance in general. There are two commands: the i-command sets the current and the c-command sets the channel.

    • Switch on current on:
      • Channel 1 “+” socket against GND: “c=1”
      • Channel 1 “-” socket against GND: “c=2”
      • Channel 2 “+” socket against GND: “c=4”
    • Set current in uA:
      • 6nA: “i=0”
      • 22nA: “i=1”
      • 6uA: “i=2”
      • 22uA: “i=3”

    Note that the Attys has protection resistors at its input sockets so that even when you short-circuit the sockets to GND you’ll measure a voltage. The series resistance is 55K which you need to subtract from any absolute resistance readings.

Disclaimer: Use the information shown on this page and the other related pages at your own risk. See the disclaimer in the CC Attribution-Noncommercial-Share Alike 3.0 Unported license. Safety first: when recording biosignals always use an electrically isolated Attys for all signal- and power-connections when conducting experiments with subjects. If you measure biosignals from other people you might need to apply for ethical approval. Make sure that the subject is electrically isolated from the mains at all times! Never record biosignals while the Attys is being charged.

Except where otherwise noted, content on this page is licensed under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International.