Overview
TinkerForge provides generic sensors and controls for diverse use cases ranging from environmental monitoring to industrial automation. Together with Cumulocity, you can
- Build complete machine-to-machine use cases by just plugging off-the-shelf hardware components together. No configuration is required – the components are automatically discovered by the Cumulocity Java agent and connected to the cloud.
- Instantly visualize sensor data and remote control devices in real-time.
Installation
Cumulocity’s Java agent supports TinkerForge out of the box. For installing and running the Java agent on the Raspberry Pi, refer to the Raspberry Pi section.
Using TinkerForge components with Cumulocity
Basic usage
Open Cumulocity in a web browser, go to “All devices” and locate the device that is running the Java agent. The “Child devices” tab lists the connected TinkerForge devices.
By default, TinkerForge components will be named using the name of the device that they are connected to (“RaspPi BCM2708 00000000e2f5ad4d” in the screenshot), the type of component (“Temperature”) and the serial number of the component (“dGW”). You can edit the name in the “Info” tab of the device.
Remote Configuration
Bricklets can be configured remotely using the c8y_Configuration operation. To access this functionality in the UI, navigate to the device running the agent. Under the control tab you will find the Configuration panel. It contains different client-side defined options that can be altered.
Barometer, humidtiy, ambient light, moisture, distance, voltage, current and temperature bricklets
Sensor data can be visualized by clicking on the “Measurements” tab of a sensor.
The data is regularly collected by the Cumulocity agent. The frequency of the collection can be configured on the Configuration panel. For example, “c8y.light.interval=5000” means that the light sensor is queried every 5.000 milliseconds.
PTC bricklet
In addition to the polling interval, you can also configure the wire mode of the PTC bricklet via the “c8y.ptc.wiremode” option. For more information on wire mode visit the TinkerForge online documentation.
LCD Display bricklet
To operate the display from Cumulocity, click the “Control” tab of the display bricklet. The “Relay” buttons switch the backlight on and off. The “Send Message” field sends a text message to be shown on the display.
The display has four buttons at the bottom. Operating these buttons will send an event to Cumulocity which is shown on the “Events” tab. You can process this event, for example, using a CEP statement. The event is of type “c8y_ButtonPressedEvent”. The number of the button is part of the text of the event.
4x7 Segment Display bricklet
The 4x7 Segment Display’s implementation is similar to that of the LCD Display bricklet. In addition you can set the display brightness in the Configuration panel through the “c8y.4x7segmentdisplay.brightness” option (Max: 7, Min: 1, Default: 4).
Remote Switch bricklet
Configuration
The Remote Switch bricklet can be used to toggle on and off various remote sockets, lamps, etc. It supports three types of addressing.
-
Type A addressing: To add a predefined type A device to the Remote Switch bricklet, append the following lines to the Configuration panel:
c8y.remoteswitch.<device name>.type=A c8y.remoteswitch.<device name>.houseCode=<house code> c8y.remoteswitch.<device name>.receiverCode=<receiver code>
Where: <device name> - the name of the device(e.g. socket1, lamp1, etc.) <house code> - 5-bit integer (0 to 31) <receiver code> - 5-bit integer (0 to 31)
-
Type B addressing: To add a predefined type B device to the Remote Switch bricklet, append the following lines to the Configuration panel:
c8y.remoteswitch.<device name>.type=B c8y.remoteswitch.<device name>.address=<address> c8y.remoteswitch.<device name>.unit=<unit>
Where: <device name> - the name of the device(e.g. socket1, lamp1, etc.). <address> - 16-bit integer (0 to 65534) <unit> - 4-bit integer (0 to 15)
-
Type C addressing: To add a predefined type C device to the Remote Switch bricklet, append the following lines to the Configuration panel:
c8y.remoteswitch.<device name>.type=C c8y.remoteswitch.<device name>.systemCode=<system code> c8y.remoteswitch.<device name>.deviceCode=<device code>
Where: <device name> - the name of the device(e.g. socket1, lamp1, etc.). <system code> - 4-bit character (A to P) <device code> - 4-bit integer (0 to 15)
For more information on Remote Switch addressing please refer to the TinkerForge documentation.
Control
The devices can be switched on and off, in alphabetical order, using the c8y_RelayArray operation. “OPEN” would mean off and “CLOSED” - on.
Example: An operation
"c8y_RelayArray" : [
"OPEN",
"CLOSED"
]
on a Remote Switch bricklet with the following configuration
c8y.remotebricklet.device2.type=B
c8y.remotebricklet.device2.address=31337
c8y.remotebricklet.device2.unit=7
c8y.remotebricklet.device1.type=C
c8y.remotebricklet.device1.systemCode=B
c8y.remotebricklet.device1.deviceCode=13
will turn off “device2” and turn on “device1”.
Dual Relay Bricklet
The dual relay bricklet consists of two relays. Each relay has three terminals such that the terminal in the middle is electrically connected to the terminal left or right depending on the relay state.
Control
The Dual Relay bricklet can be switched with the c8y_RelayArray operation.
"c8y_RelayArray" : [
"OPEN",
"CLOSED"
]
For example, the operation above will set the state of relay one to “OPEN” and relay two to “CLOSED”.
IO16 bricklet
Configuration
The IO16 bricklet consist of two ports 8-pins each. It can be configured through the Configuration panel. Available options are:
c8y.io16.porta.direction=<direction>
c8y.io16.porta.value=<value>
c8y.io16.portb.direction=<direction>
c8y.io16.portb.value=<value>
Where:
- <direction> is an 8-bit integer(0 to 255) direction mask. 0 - output, 1 - input.
- <value> is an 8-bit integer(0 to 255) value mask describing the type of input or the output value respectively. If a pin is set as output 1 and 0 will simply be the logical values. In case the pin is set as input 1 would mean pull up input and 0 would be default input.
For example, configuring port B direction to 192(11000000) and value to 88(01011000), would mean:
- pins B3, B4 are set as output with logical value 1(3,3/5 V)
- pins B0, B1, B2, B5 are set as output with logical value 0(0V)
- pin B6 is set as input with pull up
- pin B7 is set as default input
Control
The IO16 outputs can be switched with a c8y_RelayArray operation.
"c8y_RelayArray" : [
"OPEN",
"OPEN",
"CLOSED",
"OPEN"
]
This operation will find up to four outputs starting from A0 to B7 and switch them.
Distance InfraRed and UltraSound bricklets
Additionally to providing measurement data, the Distance US and IR bricklets also send events. Similar to a button press on the display, interrupting the sensor of the distance bricklets will send an event. The event can be seen on the “Events” tab of the distance bricklet and can be post-processed with CEP. The type of the event is “c8y_EntranceEvent”. Additionally the following configuration options are provided:
- c8y.distanceir.eventSlackTime, c8y.distanceus.eventSlackTime - sets the minimum time between events. Time is in ms. Default is 10000ms.
- c8y.distanceir.eventTreshold - sets the minimum distance in mm that would trigger an event. Default is 400mm;
- c8y.distanceus.eventTreshold - sets the minimum distance in % that would trigger an event. Default is 25%;
Note: The DistanceUS bricklet measures distance in percentages, where 0% would be around 2cm and 100% would be approximately 400cm. This is because the relation between the distance value and the actual distance depends on the exact value of the 5V supply voltage(deviations in the supply voltage result in deviations in the measured distance values) and is non-linear (resolution is bigger at close range).
GPS bricklet
The GPS bricklet will report its current location and send location updates as the device moves. The current location is shown in Device Management on a map and the movement history can be visualized.
Extending the TinkerForge driver
The source code for the TinkerForge driver is publicly available at https://bitbucket.org/m2m/cumulocity-examples in the folder java-agent/tinkerforge-driver.