BITalino Module

Created on Fri Jun 20 2014

Last Modified on Thur Jun 25 2015

bitalino.find()
Returns:list of (tuples) with name and MAC address of each device found

Searches for bluetooth devices nearby.

BITalino Class

class bitalino.BITalino(macAddress, timeout=None)
Parameters:
  • macAddress (str) – MAC address or serial port for the bluetooth device
  • timeout (int, float or None) – maximum amount of time (seconds) elapsed while waiting for the device to respond
Raises:
  • Exception – invalid MAC address or serial port
  • Exception – invalid timeout value

Connects to the bluetooth device with the MAC address or serial port provided.

Possible values for parameter macAddress:

  • MAC address: e.g. 00:0a:95:9d:68:16
  • Serial port - device name: depending on the operating system. e.g. COM3 on Windows; /dev/tty.bitalino-DevB on Mac OS X; /dev/ttyUSB0 on GNU/Linux.

Possible values for timeout:

Value Result
None Wait forever
X Wait X seconds for a response and raises a connection Exception
battery(value=0)
Parameters:

value (int) – threshold value

Raises:
  • Exception – device in acquisition (not IDLE)
  • Exception – threshold value is invalid

Sets the battery threshold for the BITalino device. Setting the battery threshold implies the use of the method send().

Possible values for parameter value:

Range value Corresponding threshold (Volts)
Minimum value 0 3.4 Volts
Maximum value 63 3.8 Volts
close()

Closes the bluetooth or serial port socket.

pwm(pwmOutput=100)
Parameters:

pwmOutput (int) – value for the pwm output

Raises:
  • Exception – invalid pwm output value
  • Exception – device is not a BITalino 2.0

Sets the pwm output for the BITalino 2.0 device. Implies the use of the method send().

Possible values for parameter pwmOutput: 0 - 255.

read(nSamples=100)
Parameters:

nSamples (int) – number of samples to acquire

Returns:

array with the acquired data

Raises:
  • Exception – device not in acquisition (in IDLE)
  • Exception – lost communication with the device when data is corrupted

Acquires nSamples from BITalino. Reading samples from BITalino implies the use of the method receive().

Requiring a low number of samples (e.g. nSamples = 1) may be computationally expensive; it is recommended to acquire batches of samples (e.g. nSamples = 100).

The data acquired is organized in a matrix whose lines correspond to samples and the columns are as follows:

  • Sequence Number
  • 4 Digital Channels (always present)
  • 1-6 Analog Channels (as defined in the start() method)

Example matrix for analogChannels = [0, 1, 3] used in start() method:

Sequence Number* Digital 0 Digital 1 Digital 2 Digital 3 Analog 0 Analog 1 Analog 3
0              
1              
(...)              
15              
0              
1              
(...)              

Note

*The sequence number overflows at 15

receive(nbytes)
Parameters:nbytes (int) – number of bytes to retrieve
Returns:string packed binary data
Raises Exception:
 lost communication with the device when timeout is reached

Retrieves nbytes from the BITalino device and returns it as a string pack with length of nbytes. The timeout is defined on instantiation.

send(data)

Sends a command to the BITalino device.

start(SamplingRate=1000, analogChannels=[0, 1, 2, 3, 4, 5])
Parameters:
  • SamplingRate (int) – sampling frequency (Hz)
  • analogChannels (array, tuple or list of int) – channels to be acquired
Raises:
  • Exception – device already in acquisition (not IDLE)
  • Exception – sampling rate not valid
  • Exception – list of analog channels not valid

Sets the sampling rate and starts acquisition in the analog channels set. Setting the sampling rate and starting the acquisition implies the use of the method send().

Possible values for parameter SamplingRate:

  • 1
  • 10
  • 100
  • 1000

Possible values, types, configurations and examples for parameter analogChannels:

Values 0, 1, 2, 3, 4, 5
Types list [], tuple (), array [[]]
Configurations Any number of channels, identified by their value
Examples [0, 3, 4], (1, 2, 3, 5)

Note

To obtain the samples, use the method read().

state()
Returns:

dictionary with the state of all channels

Raises:
  • Exception – device is not a BITalino version 2.0
  • Exception – device in acquisition (not IDLE)
  • Exception – lost communication with the device when data is corrupted

Returns the state of all analog and digital channels. Reading channel State from BITalino implies the use of the method send() and receive(). The returned dictionary structure contains the following key-value pairs:

Key Value Type Examples
analogChannels Value of all analog channels Array of int [A1 A2 A3 A4 A5 A6]
battery Value of the battery channel int  
batteryThreshold Value of the battery threshold int battery()
digitalChannels Value of all digital channels Array of int [I1 I2 O1 O2]
stop()
Raises Exception:
 device not in acquisition (IDLE)

Stops the acquisition. Stoping the acquisition implies the use of the method send().

trigger(digitalArray=None)
Parameters:

digitalArray (array, tuple or list of int) – array which acts on digital outputs according to the value: 0 or 1

Raises:
  • Exception – list of digital channel output is not valid
  • Exception – device not in acquisition (IDLE) (for BITalino 1.0)

Acts on digital output channels of the BITalino device. Triggering these digital outputs implies the use of the method send(). Digital Outputs can be set on IDLE or while in acquisition for BITalino 2.0.

Each position of the array digitalArray corresponds to a digital output, in ascending order. Possible values, types, configurations and examples for parameter digitalArray:

Meta BITalino 1.0 BITalino 2.0
Values 0 or 1 0 or 1
Types list [], tuple (), array [[]] list [], tuple (), array [[]]
Configurations 4 values, one for each digital channel output 2 values, one for each digital channel output
Examples [1, 0, 1, 0] [1, 0]
version()
Returns:str with the version of BITalino
Raises Exception:
 device in acquisition (not IDLE)

Retrieves the BITalino version. Retrieving the version implies the use of the methods send() and receive().