MQTT - Multi Touch Bricklet

This is the description of the MQTT API bindings for the Multi Touch Bricklet. General information and technical specifications for the Multi Touch Bricklet are summarized in its hardware description.

An installation guide for the MQTT API bindings is part of their general description.

Examples

The example code below is Public Domain (CC0 1.0).

Callback

Download (example-callback.txt)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# Change XYZ to the UID of your Multi Touch Bricklet

setup:
    # Handle incoming touch state callbacks
    subscribe to tinkerforge/callback/multi_touch_bricklet/XYZ/touch_state
        if a message arrives:
            # message contains state as int
            set result_string to ""
            if bit 12 of state is set
                append "In proximity, " to result_string
            endif
            
            if bits 0 to 11 of state are not set
                append "No electrodes touched" to result_string
            elseif
                append "Electrodes " to result_string
                for i in 0..12
                    if bit i of state is set
                        append i and " " to result_string
                    endif
                endfor
            endif
            
            print result_string   
        endif
    publish '{"register": true}' to tinkerforge/register/multi_touch_bricklet/XYZ/touch_state # register touch_state callback

Simple

Download (example-simple.txt)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# Change XYZ to the UID of your Multi Touch Bricklet

setup:
    # Get current touch state
    subscribe to tinkerforge/response/multi_touch/XYZ/get_touch_state
        if a message arrives:
            # message contains state as int
            set result_string to ""
            if bit 12 of state is set
                append "In proximity, " to result_string
            endif
            
            if bits 0 to 11 of state are not set
                append "No electrodes touched" to result_string
            elseif
                append "Electrodes " to result_string
                for i in 0..12
                    if bit i of state is set
                        append i and " " to result_string
                    endif
                endfor
            endif
            
            print result_string            
    endsubscribe
    
    publish '' to tinkerforge/request/multi_touch_bricklet/XYZ/get_touch_state 

API

All published payload to an from the MQTT bindings is in the JSON format.

If an error occures, the bindings publish a JSON object containing the error message as attribute "_ERROR". It is published on the corresponding response topic: .../response/... for .../request/... and .../callback/... for .../register/....

Basic Functions

request/multi_touch_bricklet/<UID>/get_touch_state
Response payload:
 
  • state -- int

Returns the current touch state. The state is given as a bitfield.

Bits 0 to 11 represent the 12 electrodes and bit 12 represents the proximity.

If an electrode is touched, the corresponding bit is true. If a hand or similar is in proximity to the electrodes, bit 12 is true.

Example: The state 4103 = 0x1007 = 0b1000000000111 means that electrodes 0, 1 and 2 are touched and that something is in the proximity of the electrodes.

The proximity is activated with a distance of 1-2cm. An electrode is already counted as touched if a finger is nearly touching the electrode. This means that you can put a piece of paper or foil or similar on top of a electrode to build a touch panel with a professional look.

request/multi_touch_bricklet/<UID>/recalibrate

Recalibrates the electrodes. Call this function whenever you changed or moved you electrodes.

request/multi_touch_bricklet/<UID>/set_electrode_config
Request payload:
 
  • enabled_electrodes -- int

Enables/disables electrodes with a bitfield (see request/multi_touch_bricklet/<UID>/get_touch_state).

True enables the electrode, false disables the electrode. A disabled electrode will always return false as its state. If you don't need all electrodes you can disable the electrodes that are not needed.

It is recommended that you disable the proximity bit (bit 12) if the proximity feature is not needed. This will reduce the amount of traffic that is produced by the register/multi_touch_bricklet/<UID>/touch_state callback.

Disabling electrodes will also reduce power consumption.

Default: 8191 = 0x1FFF = 0b1111111111111 (all electrodes enabled)

request/multi_touch_bricklet/<UID>/get_electrode_config
Response payload:
 
  • enabled_electrodes -- int

Returns the electrode configuration, as set by request/multi_touch_bricklet/<UID>/set_electrode_config.

request/multi_touch_bricklet/<UID>/set_electrode_sensitivity
Request payload:
 
  • sensitivity -- int

Sets the sensitivity of the electrodes. An electrode with a high sensitivity will register a touch earlier then an electrode with a low sensitivity.

If you build a big electrode you might need to decrease the sensitivity, since the area that can be charged will get bigger. If you want to be able to activate an electrode from further away you need to increase the sensitivity.

After a new sensitivity is set, you likely want to call request/multi_touch_bricklet/<UID>/recalibrate to calibrate the electrodes with the newly defined sensitivity.

The valid sensitivity value range is 5-201.

The default sensitivity value is 181.

request/multi_touch_bricklet/<UID>/get_electrode_sensitivity
Response payload:
 
  • sensitivity -- int

Returns the current sensitivity, as set by request/multi_touch_bricklet/<UID>/set_electrode_sensitivity.

Advanced Functions

request/multi_touch_bricklet/<UID>/get_identity
Response payload:
 
  • uid -- string
  • connected_uid -- string
  • position -- string
  • hardware_version -- [int,int,int]
  • firmware_version -- [int,int,int]
  • device_identifier -- int (has symbols)
  • _display_name -- string

Returns the UID, the UID where the Bricklet is connected to, the position, the hardware and firmware version as well as the device identifier.

The position can be 'a', 'b', 'c' or 'd'.

The device identifier numbers can be found here. If symbolic output is not disabled, the device identifier is mapped to the corresponding name in the format used in topics.

The display name contains the Multi Touch's name in a human readable form.

Callbacks

Callbacks can be registered to receive time critical or recurring data from the device. The registration is done with the corresponding .../register/... topic and an optional suffix. This suffix can be used to deregister the callback later.

Note

Using callbacks for recurring events is always preferred compared to using getters. It will use less USB bandwidth and the latency will be a lot better, since there is no round trip time.

register/multi_touch_bricklet/<UID>/touch_state
Request payload:
 
  • register -- bool
Response payload:
 
  • state -- int

A callback can be registered for this event by publishing to the .../register/multi_touch_bricklet/<UID>/touch_state[/<SUFFIX>] topic with the payload "true". An added callback can be removed by publishing to the same topic with the payload "false". To support multiple (de)registrations, e.g. for message filtering, an optional suffix can be used.

If the callback is triggered, a message with it's payload is published under the corresponding .../callback/multi_touch_bricklet/<UID>/touch_state[/<SUFFIX>] topic for each registered suffix.

Returns the current touch state, see request/multi_touch_bricklet/<UID>/get_touch_state for information about the state.

This callback is triggered every time the touch state changes.