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 , ANY = 0 , BAR = 1 , SQUARE = 2 , CRAFT = 3 , RING = 4 , HEX = 5 , FLEX = 6 , UNKNOWN = ANY }
enum	EventMode { kEventModeTouch = 0 , kEventModeChange = 1 , kEventModeAlways = 2 }
enum	ScanTriggerMode { kScanTriggerDisabled = 0x0 , kScanTriggerI2c = 0x1 , kScanTriggerTimer = 0x2 , kScanTriggerI2cOrTimer = 0x3 }

Public Member Functions
	Trill (unsigned int i2c_bus, Device device, uint8_t i2c_address=255)
int	setup (unsigned int i2c_bus, Device device=ANY, uint8_t i2c_address=255)
int	updateBaseline ()
int	reset ()
int	readI2C (bool shouldReadStatusByte=false)
	Read data from the device.
void	newData (const uint8_t *newData, size_t len, bool includesStatusByte=false)
	Set data retrieved from the device.
Device	deviceType ()
int	firmwareVersion ()
Mode	getMode ()
uint8_t	getAddress ()
void	printDetails ()
void	setVerbose (int verbose)
unsigned int	getNumChannels () const
unsigned int	getDefaultNumChannels () const
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 std::vector< std::pair< Device, uint8_t > >	probeRange (unsigned int i2c_bus, size_t maxCount=0)
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	setScanTrigger (ScanTriggerMode scanTriggerMode)
int	setTimerPeriod (float ms)
int	setAutoScanInterval (uint16_t interval)
int	setEventMode (EventMode mode)
int	setChannelMask (uint32_t mask)
int	setTransmissionFormat (uint8_t width, uint8_t shift)

Status byte
int	readStatusByte ()
bool	hasReset ()
bool	hasActivity ()
uint8_t	getFrameId ()
uint32_t	getFrameIdUnwrapped ()

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	getBytesToRead (bool includesStatusByte)
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.

Member Enumeration Documentation

◆ Mode

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

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

◆ Device

enum Trill::Device

The types of Trill devices

Enumerator
NONE	No device.
ANY	A valid device of unknown type.
BAR	Trill Bar
SQUARE	Trill Square
CRAFT	Trill Craft
RING	Trill Ring
HEX	Trill Hex
FLEX	Trill Flex
UNKNOWN	same as ANY, for backwards compatibility

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

◆ EventMode

enum Trill::EventMode

Controls when the EVT pin will be set when a new frame is available. In this context, the meaning "activity is detected" depends on the Mode in which the device is:

in CENTROID mode, activity is detected if one or more touches are detected
in any other mode, activity is detected if any channel after formatting is non-zero.

Enumerator
kEventModeTouch	Only set the EVT pin if activity is detected in the current frame.
kEventModeChange	Only set the EVT pin if activity is detected in the current or past frame.
kEventModeAlways	Set the EVT pin every time a new frame is available.

Examples: Trill/general-settings/render.cpp.

◆ ScanTriggerMode

enum Trill::ScanTriggerMode

Enumerator
kScanTriggerDisabled	Do not scan capacitive channels.
kScanTriggerI2c	Scan capacitive channels after every I2C transaction.
kScanTriggerTimer	Scan capacitive channels every time the timer set by setAutoScanInterval() expires.
kScanTriggerI2cOrTimer	Scan capacitive channels after every I2C transaction or when timer expires, whichever comes first.

Examples: Trill/general-settings/render.cpp.

Constructor & Destructor Documentation

◆ Trill()

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.
i2c_address	the address at which the device can be found.

If device is ANY then:

if i2c_address is a valid address, then any device detected at that addres will be accepted
if i2c_address is 255 or unspecified, then the range of valid addresses will be scanned, stopping at the first valid device encountered. Use this with caution as it may affect the behaviour of non-Trill devices on the I2C bus.

Otherwise, if i2c_address is 255 or unspecified, the default address for the specified device type will be used.

Member Function Documentation

◆ setup()

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

Initialise the device.

Parameters

i2c_bus	the bus that the device is connected to.
device	the device type.
i2c_address	the address at which the device can be found.

If device is ANY then:

if i2c_address is a valid address, then any device detected at that addres will be accepted
if i2c_address is 255 or unspecified, then the range of valid addresses will be scanned, stopping at the first valid device encountered. Use this with caution as it may affect the behaviour of non-Trill devices on the I2C bus.

Otherwise, if i2c_address is 255 or unspecified, the default address for the specified device type will be used.

Returns: 0 on success or an error code otherwise.

◆ probe()

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.

◆ probeRange()

std::vector< std::pair< Trill::Device, uint8_t > > Trill::probeRange	(	unsigned int	i2c_bus,
		size_t	maxCount = 0 )

static

Probe the bus for a device at any valid address.

Warning: Use with caution as it may affect the behaviour of non-Trill devices on the I2C bus.

Parameters

i2c_bus	the I2C bus to scan
maxCount	stop discovering new devices after this many have been discovered. Use 0 to find all possible devices.

Returns: A vector containing the Device and address pairs identified.

◆ updateBaseline()

int Trill::updateBaseline ( )

Update the baseline value on the device.

◆ reset()

int Trill::reset ( )

Reset the chip.

◆ readI2C()

int Trill::readI2C ( bool shouldReadStatusByte = false )

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

Parameters

shouldReadStatusByte whether or not to read the status byte as part of the transaction. If the firmware version is lower than 3, this should be set to false.

Returns: 0 on success or an error code otherwise.

Examples: Trill/multiple-devices/render.cpp.

◆ newData()

void Trill::newData	(	const uint8_t *	newData,
		size_t	len,
		bool	includesStatusByte = false )

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. For proper operation, this should be the value returned from getBytesToRead().
includesStatusByte	whether newData includes the status byte or not.

◆ deviceType()

Device Trill::deviceType ( )

inline

Get the device type.

◆ getNameFromDevice()

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.

◆ getDeviceFromName()

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

static

Get the device from the name.

◆ getNameFromMode()

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

static

Get the mode from the name.

◆ getModeFromName()

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

static

Get the mode from the name.

◆ firmwareVersion()

int Trill::firmwareVersion ( )

inline

Get the firmware version of the device.

◆ getMode()

Mode Trill::getMode ( )

inline

Get the mode that the device is currently in.

◆ getAddress()

uint8_t Trill::getAddress ( )

inline

Get the current address of the device.

◆ printDetails()

void Trill::printDetails ( )

Print details about the device to standard output

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

◆ setVerbose()

void Trill::setVerbose ( int verbose )

Print more details about I/O transactions as they happen.

◆ getNumChannels()

unsigned int Trill::getNumChannels ( ) const

Get the number of capacitive channels currently active on the device.

◆ getDefaultNumChannels()

unsigned int Trill::getDefaultNumChannels ( ) const

Get the number of capacitive channels available on the device.

◆ setMode()

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/general-print/render.cpp.

◆ setScanSettings()

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.

◆ setPrescaler()

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.

◆ setNoiseThreshold()

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.

◆ setIDACValue()

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.

◆ setMinimumTouchSize()

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.

◆ setScanTrigger()

int Trill::setScanTrigger ( ScanTriggerMode scanTriggerMode )

Set how the device triggers a new scan of its capacitive channels.

Parameters

arg	One of the ScanTriggerMode values

Note: This feature is only available with devices starting from firmware version 3. On older devices calling this function has no effect and it will return an error.

Returns: 0 on success or an error code otherwise.

◆ setTimerPeriod()

int Trill::setTimerPeriod ( float ms )

Set the interval for scanning capacitive channels when the device's scanning is triggered by the timer.

Parameters

ms the scanning period, measured in milliseconds. The effective minimum scanning period will be limited by the scanning speed, bit depth and any computation happening on the device (such as touch detection). Granularity is 1 ms for values until 255 ms and higher after that. Maximum value is just above 2032 ms. Scanning on timer has to be separately enabled via setScanTrigger(). When ms is not greater than zero, the timer is disabled.

Note: The 32kHz clock often deviates by 10% or more from its nominal frequency, thus affecting the accuracy of the timer.

◆ setAutoScanInterval()

int Trill::setAutoScanInterval ( uint16_t interval )

Deprecated. Same as setTimerPeriod(), but the interval is expressed as cycles of a 32kHz clock. On devices with firmware 2, interval is used directly. On devices with firwmare 3 or above, it is quantised to blocks of at least 1 ms.

◆ setEventMode()

int Trill::setEventMode ( EventMode mode )

Set how the EVT pin behaves.

Parameters

mode	an EventMode denoting the required behaviour.

Returns: 0 on success or an error code otherwise.

Note: This feature is only available with devices starting from firmware version 3. On older devices calling this function has no effect and it will return an error.

◆ setChannelMask()

int Trill::setChannelMask ( uint32_t mask )

Set a channel mask identifying which scanning channels are enabled.

Parameters

mask	The channel mask. Bits 0 to 31 identify channels 0 to 31 respectively. Bit positions higher than the value returned by getDefaultNumChannels() are ignored.

Returns: 0 on success or an error code otherwise.

Note: This feature is only available with devices starting from firmware version 3. On older devices calling this function has no effect and it will return an error.

◆ setTransmissionFormat()

int Trill::setTransmissionFormat	(	uint8_t	width,
		uint8_t	shift )

Set the format used for transmission of non-centroid data from the device to the host.

Parameters

width	The data width. If a value would overflow when stored, it is clipped.
shift	Number of right shift operations applied on the value before being stored in the word.

Returns: 0 on success or an error code otherwise.

Note: This feature is only available with devices starting from firmware version 3. On older devices calling this function has no effect and it will return an error.

◆ readStatusByte()

int Trill::readStatusByte ( )

Read the status byte from the device. Alternatively, the status byte can be read as part of reading data by calling readI2C(true).

Returns: the status byte, or a negative value in case of error. As a successful call also updates the internal state, the caller is probably better off calling getFrameId(), hasActivity(), hasReset() instead of parsing the status byte directly.

Note: This feature is only available with devices starting from firmware version 3. On older devices calling this function has no effect and its return value is undefined.

◆ hasReset()

bool Trill::hasReset ( )

Whether the device has reset since a identify command was last written to it.

This relies on a current status byte.

Note: This feature is only available with devices starting from firmware version 3. On older devices calling this function has no effect and it will return an error.

◆ hasActivity()

bool Trill::hasActivity ( )

Whether activity has been detected in the current frame.

This relies on a current status byte.

Note: This feature is only available with devices starting from firmware version 3. On older devices calling this function has no effect and its return value is undefined.

◆ getFrameId()

uint8_t Trill::getFrameId ( )

Get the frameId. This relies on a current status byte.

Note: This feature is only available with devices starting from firmware version 3. On older devices calling this function has no effect and its return value is undefined.

◆ getFrameIdUnwrapped()

uint32_t Trill::getFrameIdUnwrapped ( )

Same as above, but it tries to unwrap the 6-bit frameId into a uint32_t counter. This relies on reading several status bytes over time. The counter is guaranteed monotonic, but it can only be regarded as an actual frame counter if the status byte is read at least once every 63 frames.

Returns: the counter

Note: This feature is only available with devices starting from firmware version 3. On older devices calling this function has no effect and its return value is undefined.

◆ is1D()

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.

◆ is2D()

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.

◆ getBytesToRead()

unsigned int Trill::getBytesToRead ( bool includesStatusByte )

Return the number of bytes to read when reading data.

◆ getNumButtons()

unsigned int Trill::getNumButtons ( )

inline

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

◆ getNumTouches()

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.

◆ touchLocation()

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.

◆ touchSize()

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.

◆ getNumHorizontalTouches()

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

◆ touchHorizontalLocation()

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.

◆ touchHorizontalSize()

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.

◆ compoundTouchLocation()

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.

◆ compoundTouchHorizontalLocation()

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.

◆ compoundTouchSize()

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.

◆ getButtonValue()

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

◆ rawData

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.

◆ speedValues

uint8_t Trill::speedValues = {0, 1, 2, 3}

staticconstexpr

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

◆ prescalerMax

uint8_t Trill::prescalerMax = 8

staticconstexpr

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

Status byte

Centroid Mode

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Mode

◆ Device

◆ EventMode

◆ ScanTriggerMode

Constructor & Destructor Documentation

◆ Trill()

Member Function Documentation

◆ setup()

◆ probe()

◆ probeRange()

◆ updateBaseline()

◆ reset()

◆ readI2C()

◆ newData()

◆ deviceType()

◆ getNameFromDevice()

◆ getDeviceFromName()

◆ getNameFromMode()

◆ getModeFromName()

◆ firmwareVersion()

◆ getMode()

◆ getAddress()

◆ printDetails()

◆ setVerbose()

◆ getNumChannels()

◆ getDefaultNumChannels()

◆ setMode()

◆ setScanSettings()

◆ setPrescaler()

◆ setNoiseThreshold()

◆ setIDACValue()

◆ setMinimumTouchSize()

◆ setScanTrigger()

◆ setTimerPeriod()

◆ setAutoScanInterval()

◆ setEventMode()

◆ setChannelMask()

◆ setTransmissionFormat()

◆ readStatusByte()

◆ hasReset()

◆ hasActivity()

◆ getFrameId()

◆ getFrameIdUnwrapped()

◆ is1D()

◆ is2D()

◆ getBytesToRead()

◆ getNumButtons()

◆ getNumTouches()

◆ touchLocation()

◆ touchSize()

◆ getNumHorizontalTouches()

◆ touchHorizontalLocation()

◆ touchHorizontalSize()

◆ compoundTouchLocation()

◆ compoundTouchHorizontalLocation()

◆ compoundTouchSize()

◆ getButtonValue()

Member Data Documentation

◆ rawData

◆ speedValues

◆ prescalerMax