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

#include <Trill.h>

Inheritance diagram for Trill:

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...

void	newData (const uint8_t *newData, size_t len)
	Set data retrieved from the device. More...

int	prepareForDataRead ()
	Prepare the device so that successive reads will return data. More...

Device	deviceType ()

int	firmwareVersion ()

Mode	getMode ()

uint8_t	getAddress ()

void	printDetails ()

unsigned int	getNumChannels ()

Public Member Functions inherited from I2c
ssize_t	readBytes (void *buf, size_t count)

ssize_t	writeBytes (const void *buf, size_t count)

	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/bar-led/render.cpp, Trill/bar-sound/render.cpp, Trill/bar-visual/render.cpp, Trill/craft-sound/render.cpp, Trill/craft-visual/render.cpp, Trill/custom-slider/render.cpp, Trill/flex-default/render.cpp, Trill/flex-visual/render.cpp, Trill/general-custom-address/render.cpp, Trill/general-print/render.cpp, Trill/general-settings/render.cpp, Trill/general-visual/render.cpp, Trill/hex-sound/render.cpp, Trill/hex-visual/render.cpp, Trill/multiple-devices/render.cpp, Trill/ring-sound/render.cpp, Trill/ring-visual/render.cpp, Trill/square-multitouch/render.cpp, Trill/square-sound/render.cpp, and Trill/square-visual/render.cpp.

Member Enumeration Documentation

enum Trill::Mode

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

enum Trill::Device

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_bus	the bus that the device is connected to.
device	the 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_address	the 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_bus	the bus that the device is connected to.
device	the 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_address	the 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/bar-led/render.cpp, Trill/bar-sound/render.cpp, Trill/bar-visual/render.cpp, Trill/craft-sound/render.cpp, Trill/craft-visual/render.cpp, Trill/custom-slider/render.cpp, Trill/flex-default/render.cpp, Trill/flex-visual/render.cpp, Trill/general-custom-address/render.cpp, Trill/general-print/render.cpp, Trill/general-settings/render.cpp, Trill/general-visual/render.cpp, Trill/hex-sound/render.cpp, Trill/hex-visual/render.cpp, Trill/ring-sound/render.cpp, Trill/ring-visual/render.cpp, Trill/square-multitouch/render.cpp, Trill/square-sound/render.cpp, and Trill/square-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.

Examples:: Trill/detect-all-devices/render.cpp, and Trill/multiple-devices/render.cpp.

int Trill::updateBaseline ( )

Update the baseline value on the device.

Examples:: Trill/craft-visual/render.cpp, Trill/flex-visual/render.cpp, and Trill/general-settings/render.cpp.

int Trill::readI2C ( )

Read data from the device.

Performs an I2C transaction with the device to retrieve new data and parse them. Users calling this method won't need to call newData().

Examples:: Trill/bar-led/render.cpp, Trill/bar-sound/render.cpp, Trill/bar-visual/render.cpp, Trill/craft-sound/render.cpp, Trill/craft-visual/render.cpp, Trill/custom-slider/render.cpp, Trill/flex-default/render.cpp, Trill/flex-visual/render.cpp, Trill/general-custom-address/render.cpp, Trill/general-print/render.cpp, Trill/general-settings/render.cpp, Trill/general-visual/render.cpp, Trill/hex-sound/render.cpp, Trill/hex-visual/render.cpp, Trill/multiple-devices/render.cpp, Trill/ring-sound/render.cpp, Trill/ring-visual/render.cpp, Trill/square-multitouch/render.cpp, Trill/square-sound/render.cpp, and Trill/square-visual/render.cpp.

void Trill::newData	(	const uint8_t *	newData,
		size_t	len
	)

Set data retrieved from the device.

Sets the data retrieved from the device. This can be used to pass to the object data retrieved elsewhere (e.g.: from an I2C DMA callback). Users calling readI2C() won't need to call this method.

Parameters

newData	A pointer to an array containing new data.
len	The length of the array.

int Trill::prepareForDataRead ( )

Prepare the device so that successive reads will return data.

This should be called once before trying to read I2C bytes from the device via an external method. It is not needed to call this when using readI2C().

Device Trill::deviceType ( )

inline

Get the device type.

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

static

Get the name from the device.

Examples:: Trill/detect-all-devices/render.cpp, and Trill/multiple-devices/render.cpp.

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.

Examples:: Trill/general-custom-address/render.cpp.

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/bar-led/render.cpp, Trill/bar-sound/render.cpp, Trill/bar-visual/render.cpp, Trill/craft-sound/render.cpp, Trill/custom-slider/render.cpp, Trill/flex-default/render.cpp, Trill/general-custom-address/render.cpp, Trill/general-print/render.cpp, Trill/general-settings/render.cpp, Trill/general-visual/render.cpp, Trill/hex-sound/render.cpp, Trill/hex-visual/render.cpp, Trill/ring-sound/render.cpp, Trill/ring-visual/render.cpp, Trill/square-multitouch/render.cpp, Trill/square-sound/render.cpp, and Trill/square-visual/render.cpp.

unsigned int Trill::getNumChannels ( )

Get the number of capacitive channels on the device.

Examples:: Trill/craft-visual/render.cpp, Trill/flex-visual/render.cpp, Trill/general-custom-address/render.cpp, Trill/general-print/render.cpp, Trill/general-settings/render.cpp, and Trill/general-visual/render.cpp.

int Trill::setMode ( Mode mode )

Set the operational mode of the device.

Parameters

mode	The 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/craft-visual/render.cpp, Trill/custom-slider/render.cpp, Trill/flex-visual/render.cpp, Trill/general-print/render.cpp, Trill/general-settings/render.cpp, and Trill/general-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

speed	The 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_bits	The bit depth of the scanning. Valid values are comprised between 9 and 16.

Returns: 0 on success, or an error code otherwise.

Examples:: Trill/craft-visual/render.cpp, Trill/flex-visual/render.cpp, and Trill/general-settings/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

prescaler The 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/craft-visual/render.cpp, Trill/flex-visual/render.cpp, and Trill/general-settings/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

threshold the 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/craft-visual/render.cpp, Trill/flex-visual/render.cpp, and Trill/general-settings/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

value the 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

interval The 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.

Examples:: Trill/general-custom-address/render.cpp.

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/bar-led/render.cpp, Trill/bar-sound/render.cpp, Trill/bar-visual/render.cpp, Trill/flex-default/render.cpp, Trill/general-custom-address/render.cpp, Trill/ring-sound/render.cpp, Trill/ring-visual/render.cpp, and Trill/square-multitouch/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_num the 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/bar-led/render.cpp, Trill/bar-sound/render.cpp, Trill/bar-visual/render.cpp, Trill/flex-default/render.cpp, Trill/general-custom-address/render.cpp, Trill/ring-sound/render.cpp, Trill/ring-visual/render.cpp, and Trill/square-multitouch/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/bar-led/render.cpp, Trill/bar-sound/render.cpp, Trill/bar-visual/render.cpp, Trill/flex-default/render.cpp, Trill/ring-sound/render.cpp, Trill/ring-visual/render.cpp, and Trill/square-multitouch/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

Examples:: Trill/square-multitouch/render.cpp.

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_num the 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.

Examples:: Trill/general-custom-address/render.cpp, and Trill/square-multitouch/render.cpp.

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.

Examples:: Trill/hex-sound/render.cpp, Trill/hex-visual/render.cpp, Trill/ring-sound/render.cpp, Trill/square-sound/render.cpp, and Trill/square-visual/render.cpp.

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.

Examples:: Trill/hex-sound/render.cpp, Trill/hex-visual/render.cpp, Trill/square-sound/render.cpp, and Trill/square-visual/render.cpp.

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.

Examples:: Trill/hex-sound/render.cpp, Trill/hex-visual/render.cpp, Trill/ring-sound/render.cpp, Trill/square-sound/render.cpp, and Trill/square-visual/render.cpp.

float Trill::getButtonValue ( uint8_t button_num )

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

Parameters

button_num the 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/craft-sound/render.cpp, Trill/craft-visual/render.cpp, Trill/custom-slider/render.cpp, Trill/flex-visual/render.cpp, Trill/general-custom-address/render.cpp, Trill/general-print/render.cpp, Trill/general-settings/render.cpp, and Trill/general-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:

libraries/Trill/Trill.h
libraries/Trill/Trill.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

RAW, BASELINE or DIFF mode

Scan Configuration Settings

Centroid Mode

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation