Bela
Real-time, ultra-low-latency audio and sensor processing system for BeagleBone Black
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
Trill Class Reference

A class to use the Trill family of capacitive sensors. http://bela.io/trill. More...

#include <Trill.h>

Inheritance diagram for Trill:
I2c

Public Types

enum  Mode {
  AUTO = -1, CENTROID = 0, RAW = 1, BASELINE = 2,
  DIFF = 3
}
 
enum  Device {
  NONE = -1, UNKNOWN = 0, BAR = 1, SQUARE = 2,
  CRAFT = 3, RING = 4, HEX = 5, FLEX = 6
}
 

Public Member Functions

 Trill (unsigned int i2c_bus, Device device, uint8_t i2c_address=255)
 
int setup (unsigned int i2c_bus, Device device, uint8_t i2c_address=255)
 
int updateBaseline ()
 
int readI2C ()
 Read data from the device. More...
 
Device deviceType ()
 
int firmwareVersion ()
 
Mode getMode ()
 
uint8_t getAddress ()
 
void printDetails ()
 
unsigned int getNumChannels ()
 
- Public Member Functions inherited from I2c
 I2c (I2c &&)=delete
 
int initI2C_RW (int bus, int address, int file)
 
int closeI2C ()
 

Static Public Member Functions

static Device probe (unsigned int i2c_bus, uint8_t i2c_address)
 
static const std::string & getNameFromDevice (Device device)
 
static Device getDeviceFromName (const std::string &name)
 
static const std::string & getNameFromMode (Mode mode)
 
static Mode getModeFromName (const std::string &name)
 

Static Public Attributes

static constexpr uint8_t speedValues [4] = {0, 1, 2, 3}
 
static constexpr uint8_t prescalerMax = 8
 

RAW, BASELINE or DIFF mode

When the device is in RAW, BASELINE, or DIFF mode, the readings from the individual sensing channels are accessed through rawData.

std::vector< float > rawData
 

Scan Configuration Settings

Some of the methods below map directly to function calls and variables with the CSD_ prefix, which are described in the Cypress CapSense Sigma-Delta * Datasheet v2.20.

int setMode (Mode mode)
 
int setScanSettings (uint8_t speed, uint8_t num_bits=12)
 
int setPrescaler (uint8_t prescaler)
 
int setNoiseThreshold (float threshold)
 
int setIDACValue (uint8_t value)
 
int setMinimumTouchSize (float minSize)
 
int setAutoScanInterval (uint16_t interval)
 

Centroid Mode

When the device is in CENTROID mode, touches are detected as discrete entities and can be retrieved with the methods in this section.

The location of a touch is a normalised value where 0 and 1 are the extremes of the axis.

The size of a touch is a rescaled value of the total activation measured on the sensing channels that contribute to the touch. The amount of activation for a touch of a given size is dependent (among other things) on the geometry of the device. The values used here have been determined empirically.

A compoundTouch is a single touch represntation obtained by averaging the location and size of the touches on each axis and their size. This is most useful for 2-axes devices, in order to get a single touch.

bool is1D ()
 
bool is2D ()
 
unsigned int getNumButtons ()
 
unsigned int getNumTouches ()
 
float touchLocation (uint8_t touch_num)
 
float touchSize (uint8_t touch_num)
 
unsigned int getNumHorizontalTouches ()
 
float touchHorizontalLocation (uint8_t touch_num)
 
float touchHorizontalSize (uint8_t touch_num)
 
float compoundTouchLocation ()
 
float compoundTouchHorizontalLocation ()
 
float compoundTouchSize ()
 
float getButtonValue (uint8_t button_num)
 

Additional Inherited Members

- Protected Attributes inherited from I2c
int i2C_bus
 
int i2C_address
 
int i2C_file
 

Detailed Description

A class to use the Trill family of capacitive sensors. http://bela.io/trill.

Examples:
Trill/flex-default/render.cpp, and Trill/flex-visual/render.cpp.

Member Enumeration Documentation

The acquisition modes that a device can be set to.

Enumerator
AUTO 

Auto mode: the mode is set automatically based on the device type

CENTROID 

Centroid mode: detect discrete touches

RAW 

Raw mode

BASELINE 

Baseline mode

DIFF 

Differential mode

The types of Trill devices

Enumerator
NONE 

No device.

UNKNOWN 

A valid device of unknown type.

BAR 

Trill Bar

SQUARE 

Trill Square

CRAFT 

Trill Craft

RING 

Trill Ring

HEX 

Trill Hex

FLEX 

Trill Flex

Constructor & Destructor Documentation

Trill::Trill ( unsigned int  i2c_bus,
Device  device,
uint8_t  i2c_address = 255 
)

Initialise the device.

Parameters
i2c_busthe bus that the device is connected to.
devicethe device type. If UNKNOWN is passed, then the i2c_address parameter has to be a valid address, and any detected device type will be accepted. If something else than UNKNOWN is passed, and the detected device type is different from the requested one, the function will fail and the object will be left uninitialised.
i2c_addressthe address at which the device can be found. If 255 or no value is passed, the default address for the specified device type will be used.

Member Function Documentation

int Trill::setup ( unsigned int  i2c_bus,
Device  device,
uint8_t  i2c_address = 255 
)

Initialise the device.

Parameters
i2c_busthe bus that the device is connected to.
devicethe device type. If UNKNOWN is passed, then the i2c_address parameter has to be a valid address, and any detected device type will be accepted. If something else than UNKNOWN is passed, and the detected device type is different from the requested one, the function will fail and the object will be left uninitialised.
i2c_addressthe address at which the device can be found. If 255 or no value is passed, the default address for the specified device type will be used.
Returns
0 upon success, an error code otherwise.
Examples:
Trill/flex-default/render.cpp, and Trill/flex-visual/render.cpp.
Trill::Device Trill::probe ( unsigned int  i2c_bus,
uint8_t  i2c_address 
)
static

Probe the bus for a device at the specified address.

Returns
The type of the device that was found. If no device was found, NONE is returned.
int Trill::updateBaseline ( )

Update the baseline value on the device.

Examples:
Trill/flex-visual/render.cpp.
int Trill::readI2C ( )
virtual

Read data from the device.

Performs an I2C transaction with the device to retrieve new data.

Implements I2c.

Examples:
Trill/flex-default/render.cpp, and Trill/flex-visual/render.cpp.
Device Trill::deviceType ( )
inline

Get the device type.

const std::string & Trill::getNameFromDevice ( Device  device)
static

Get the name from the device.

Trill::Device Trill::getDeviceFromName ( const std::string &  name)
static

Get the device from the name.

const std::string & Trill::getNameFromMode ( Mode  mode)
static

Get the mode from the name.

Trill::Mode Trill::getModeFromName ( const std::string &  name)
static

Get the mode from the name.

int Trill::firmwareVersion ( )
inline

Get the firmware version of the device.

Mode Trill::getMode ( )
inline

Get the mode that the device is currently in.

uint8_t Trill::getAddress ( )
inline

Get the current address of the device.

void Trill::printDetails ( )

Print details about the device to standard output

Examples:
Trill/flex-default/render.cpp.
unsigned int Trill::getNumChannels ( )

Get the number of capacitive channels on the device.

Examples:
Trill/flex-visual/render.cpp.
int Trill::setMode ( Mode  mode)

Set the operational mode of the device.

Parameters
modeThe device mode. The special mode AUTO, selects the device-specific default mode for the detected device type.
Returns
0 on success, or an error code otherwise.
Examples:
Trill/flex-visual/render.cpp.
int Trill::setScanSettings ( uint8_t  speed,
uint8_t  num_bits = 12 
)

Set the speed and bit depth of the capacitive scanning. This triggers a call to CSD_SetScanMode(speed, num_bits) on the device.

Parameters
speedThe speed of the scanning Valid values of speed are, ordered by decreasing speed, are comprised between 0 (CSD_ULTRA_FAST_SPEED) and 3 (CSD_SLOW_SPEED)
num_bitsThe bit depth of the scanning. Valid values are comprised between 9 and 16.
Returns
0 on success, or an error code otherwise.
Examples:
Trill/flex-visual/render.cpp.
int Trill::setPrescaler ( uint8_t  prescaler)

Set the prescaler value for the capacitive scanning. This triggers a call to CSD_SetPrescaler(prescaler) on the device.

Parameters
prescalerThe prescaler value. Valid values are between 0 and 8, inclusive, and map directly to values CSD_PRESCALER_1 to CSD_PRESCALER_256.
Returns
0 on success, or an error code otherwise.
Examples:
Trill/flex-visual/render.cpp.
int Trill::setNoiseThreshold ( float  threshold)

Set the noise threshold for the capacitive channels.

When a channel's scan returns a value smaller than the threshold, its value is set to 0.

Parameters
thresholdthe noise threshold level. Valid values are between 0 and 255.0/(1 << numBits). The value is internally converted to an 8-bit integer by multiplying it times 1 << numBits before being sent to the device. On the device, the received value is used to set the CSD_bNoiseThreshold variable.
Returns
0 on success, or an error code otherwise.
Examples:
Trill/flex-visual/render.cpp.
int Trill::setIDACValue ( uint8_t  value)

Sets the IDAC value for the device.

This triggers a call to CSD_SetIdacValue(value) on the device.

Parameters
valuethe IDAC value. Valid values are between 0 and 255.
Returns
0 on success, or an error code otherwise.
int Trill::setMinimumTouchSize ( float  minSize)

Set minimum touch size

Sets the minimum touch size below which a touch is ignored.

Returns
0 on success, or an error code otherwise.
int Trill::setAutoScanInterval ( uint16_t  interval)

Set the device to scan automatically at the specified intervals.

Parameters
intervalThe scanning period, measured in ticks of a 32kHz clock. This effective scanning period will be limited by the scanning speed, bit depth and any computation happening on the device (such as touch detection). A value of 0 disables auto scanning.
Returns
0 on success, or an error code otherwise.
bool Trill::is1D ( )

Does the device have one axis of position sensing?

Returns
true if the device has one axis of position sensing and is set in CENTROID mode, false otherwise.
bool Trill::is2D ( )

Does the device have two axes of position sensing?

Returns
true if the device has two axes of position sensing and is set in CENTROID mode, false otherwise.
unsigned int Trill::getNumButtons ( )
inline

Return the number of "button" channels on the device.

unsigned int Trill::getNumTouches ( )

Get the number of touches currently active on the vertical axis of the device.

Note
It is only valid to call this method if one of is1D() and is2D() returns true.
Examples:
Trill/flex-default/render.cpp.
float Trill::touchLocation ( uint8_t  touch_num)

Get the location of a touch on the vertical axis of the device.

Note
It is only valid to call this method if one of is1D() and is2D() returns true.
Parameters
touch_numthe number of the touch. This value needs to be comprised between 0 and getNumTouches() - 1.
Returns
the position of the touch relative to the axis, or -1 if no such touch exists.
Examples:
Trill/flex-default/render.cpp.
float Trill::touchSize ( uint8_t  touch_num)

Get the size of a touch.

Note
It is only valid to call this method if one of is1D() and is2D() returns true.
Returns
the size of the touch, if the touch exists, or 0 otherwise.
Examples:
Trill/flex-default/render.cpp.
unsigned int Trill::getNumHorizontalTouches ( )

Get the number of touches currently active on the horizontal axis of the device.

Note
It is only valid to call this method is2D() returns true
float Trill::touchHorizontalLocation ( uint8_t  touch_num)

Get the location of a touch on the horizontal axis of the device.

Note
It is only valid to call this method is2D() returns true
Parameters
touch_numthe number of the touch. This value needs to be comprised between 0 and getNumHorizontalTouches() - 1.
Returns
the position of the touch relative to the axis, or -1 if no such touch exists.
float Trill::touchHorizontalSize ( uint8_t  touch_num)

Get the size of a touch.

Note
It is only valid to call this method is2D() returns true
Returns
the size of the touch, if the touch exists, or 0 otherwise.
float Trill::compoundTouchLocation ( )

Get the vertical location of the compound touch on the device.

Note
It is only valid to call this method if one of is1D() and is2D() returns true.
float Trill::compoundTouchHorizontalLocation ( )

Get the horizontal location of the compound touch on the device.

Note
It is only valid to call this method if one of is1D() and is2D() returns true.
float Trill::compoundTouchSize ( )

Get the size of the compound touch on the device.

Note
It is only valid to call this method if one of is1D() and is2D() returns true.
float Trill::getButtonValue ( uint8_t  button_num)

Get the value of the capacitive "button" channels on the device

Parameters
button_numthe button number. Valid values are comprised between 0 and getNumButtons() - 1.
Returns
The differential reading on the button, normalised between 0 and 1.

Member Data Documentation

std::vector<float> Trill::rawData

An array containing the readings from the device's channel when the device is in RAW, BASELINE or DIFF mode.

The type of data it contains depend on the device mode:

  • RAW: the rawData array contains the raw readings of each individual capacitive sensing channel. This corresponds to CSD_waSnsResult.
  • BASELINE:the rawData array contains the baseline readings of each individual capacitive sensing channel. This corresponds to CSD_waSnsBaseline.
  • DIFF: the rawData array contains differential readings between the baseline and the raw reading. This corresponds to CSD_waSnsDiff.
Examples:
Trill/flex-visual/render.cpp.
constexpr uint8_t Trill::speedValues = {0, 1, 2, 3}
static

An array containing the valid values for the speed parameter in setScanSettings()

constexpr uint8_t Trill::prescalerMax = 8
static

The maximum value for the setPrescaler() method


The documentation for this class was generated from the following files: