This document is a practical guide of using the BigClown IoT Kit. It will guide you how Raspberry Pi can read the temperature from Core Module, control the LED, measure the relative air humidity from Humidity Tag, control small electronic devices using Relay Module.

You will also be able to create a wireless network using USB Dongle. Data acqusition and control process is demonstrated using Node-RED, a web application that will run inside the Raspberry Pi. This application allows intuitive graphical automation flow editing directly in your web browser.

This tutorial is divided into several chapters. We suggest to study them one by one. The subsequent chapter builds on the knowledge from the previous chapters. At the end of each chapter there is a link to more detailed instructions, which can help you in case of confusion.

First we will demonstrate basic functionality without a wireless network. We use just a single Core Module connected to the Raspberry Pi by a USB cable.

What will we need at minimum:

Optionally for establishing a wireless network, you will need:

Raspberry Pi Installation

The easiest way to start is to download the BigClown Raspbian image. This image has already pre-installed necessary components. It contains BigClown Gateway, Mosquitto MQTT broker, Node-RED and BigClown Firmware Tool (bcf).

The downloaded Raspberry Pi image has to be written to a MicroSD card using the dd command or using the Win32DiskImager tool.

You can also download the official Raspbian and install necessary packages yourself.

Raspberry Pi Login

  1. Insert the MicroSD card with the Raspbian image to the Raspberry Pi.
  2. Connect the Ethernet cable to the Raspberry Pi.
  3. Connect the Core Module or the USB Dongle to the Raspberry Pi.
  4. Connect the power adapter to the Raspberry Pi.

After the Raspberry Pi boots up you should be able to find it at address hub.local. You can try the command ping hub.local and see the response.

Please log on the Raspberry Pi shell by typing ssh pi@hub.localhost command or use the Windows program PuTTY.

Firmware Upload

For quick start we've create a Python command-line utility bcf, which automatically downloads latest released firmwares from GitHub and will flash the modules. On the Raspberry Pi you need first to update the list of releases by typing bcf update. Then by typing bcf list you get the list of pre-compiled firmwares.

We'll flash the bcf-gateway firmware. This firmware for the gateway contains functions for all BigClown sensors and modules. After the start the Core Module automatically detects connected sensors and sends the measured values by USB to the Raspberry Pi.

Before flashing is necessary to switch the Core Module to the programming DFU mode.

bcf flash --dfu bigclownlabs/bcf-gateway-core-module:latest

After the firmware flashing the Core Module will automatically restart and the flashed firmware will be run.

USB-MQTT communication bridge

USB Dongle or Core Module with the gateway firmware is using virtual serial port over USB to exchange the data. This communication is then redirected on the Raspberry Pi to the MQTT messages thanks to the bch-gateway service.

All the messages from modules go through the gateway to the MQTT broker. The MQTT is an open standard and also our back-bone system for passing the messages both ways. In the middle of this communication system is the MQTT broker. Which is a server that accepts client connections. Between the broker and clients are flowing MQTT messages. Each of them contains topic and payload. Topic is a text string and has directory-like structure with the / delimeter (eg. node/core-module:0/thermometer/0:1/temperature). Payload isn't defined by a MQTT standard and BigClown is sending these data types: numbers, strings, boolean values and JSONs.

Other services can easily connect to the MQTT broker and extend the functionality. Like Node-RED, MQTT-Spy or Android MQTT Dash application.

Another option is to enaable port-formwarding of the MQTT port (1883) on you NAT/network router. Then you can connect to your broker from anywhere in the world. It is also possible to set-up a bridge with other Mosquitto MQTT brokers. All the brokers then share the same messages between each other. Both of these described methods needs proper security settings. For example by TLS connection.

Subscribing and publishing MQTT messages

This chapter is there for completion. Reading of the measured values is explained also in the next chapter with graphical Node-RED application.

There's a Core Module connected to the Raspberry Pi. Now we display the measured data which are send by the MQTT broker.

First we try to subscribe to the topic with mosquitto_sub command-line utility. For publishing MQTT messages there's another utility mosquitto_pub. Pelase write the command below to your Raspberry Pi

mosquitto_sub -t "#" -v

After a while you should see a messages from the temperature sensor on the Core Module. You can also see the button events when you press the B button on the Core Module.

pi@hub:~ $ mosquitto_sub -t "#" -v
node/core-module:0/thermometer/0:1/temperature 24.69
node/core-module:0/thermometer/0:1/temperature 24.94
node/core-module:0/push-button/-/event-count 5

The -t parameter if for topic which we would like to subscribe. The hash symbol # means that we would like to subscribe to all topics. The parameter -v displays more verbose output to the console, so we can see not only values but also messages topics.

Another MQTT wildcard symbol is question mark ?, which has the similar functionality like #, but it can be used only in one MQTT topic level (topic to read all thermometers node/?/thermometer).

We'll try to turn on an LED on the Core Module.

mosquitto_pub -t "node/core-module:0/led/-/state/set" -m true

Perfect! That was simple, right? Now let's learn the Node-RED.

Opening the Node-RED

Node-RED is a web application pre-installed in BigClown Raspbian which runs on Raspberry Pi. You can run it in your web browser and display, process measured values and then send commands to other modules like Relay Module, Power Module, LCD Module.

Please type the hub.local:1800 address to your web browser.

Node-RED

On the left panel you choose the building blocks which you place by dragging and dropping to the middle to the flow. Blocks are divided to several sections, the most important are input, output, function and dashboard. After the placement of the blocks you can connect them with wires and create a flow.

On the right side of the screen there are tabs info and very important tab debug. Later we will use also the dashboard tab to open our own designed page with gauges, switches and buttons.

When you create any change in the flow or configuration, you have to apply the changes by pressing the deploy button at the top right corner of the screen.

More information is in the Node-RED for Automation.

Subscribing to the MQTT messages in Node-RED

First we will output all the incoming MQTT messages to the debug output. The following procedure will explain how to create basic flow printing all MQTT messages to the debug tab. You can follow this instructions or import the flow below by the Import option in the top right menu.

[{"id":"2c3b9c0.ff19564","type":"tab","label":"Flow 0","disabled":false,"info":""},{"id":"fda6ba0.64ecb48","type":"mqtt in","z":"2c3b9c0.ff19564","name":"","topic":"#","qos":"2","broker":"ba3b2e25.7c8b7","x":170,"y":100,"wires":[["2dbd1aa6.284476"]]},{"id":"2dbd1aa6.284476","type":"debug","z":"2c3b9c0.ff19564","name":"","active":true,"console":"false","complete":"false","x":390,"y":100,"wires":[]},{"id":"ba3b2e25.7c8b7","type":"mqtt-broker","z":"","broker":"localhost","port":"1883","clientid":"","usetls":false,"compatmode":true,"keepalive":"60","cleansession":true,"willTopic":"","willQos":"0","willPayload":"","birthTopic":"","birthQos":"0","birthPayload":""}]

If you would like to create this flow manually, please follow these instructions. From the input section drag and drop the mqtt block to the empty flow. After that select and place from the output section the debug block. Now you need to connect these blocks by the mouse. This way you have created your first flow.

Now it is necessary to configure mqtt block. By double clicking on the block open the setting and set these parameters:

  • server: localhost:1883
  • topic: #

After you save the block settings you have to apply the changes by the deploy button. After deploying switch to the debug tab and after few moments you'll see incoming messages from connected Core Module. You can also press B button on the Core Module and this event will also appear in the debug log.

Displaying the temperature

Now you can see all the incoming messages. In case we would like to receive only temperature from one module, we have to change the topic in the mqtt block. We need to change # to the node/core-module:0/thermometer/0:1/temperature.

For the graphical representation of received values you can use Node-RED dasboard. Please insert the gauge block, which is in the left list of the block at the bottom. This block needs to be configured.

Double click on the gauge block for configuration. First create the new dashboard group by clicking the pencil symbol at the Add new ui_group field. In the next opened dialog again click the pencil symbol at the Add new ui_tab. Now confirm both opened dialogs and the default dashboard tab and group is created. Before closing the gauge settings change the Range of the gauge to values from 0 to 40 and confirm this last opened dialog. Press the deploy to apply the changes and open the dasboard.

Dashboard can be opened in the right dashboard tab by clicking on the arrow symbol or by typing the hub.local:1880/ui address to your browser.

Here's the complete flow in case of any issues.

[{"id":"3bfb0014.c8ac9","type":"mqtt in","z":"e2a5ec72.0af0b","name":"","topic":"node/core-module:0/thermometer/0:1/temperature","qos":"2","broker":"86ef748c.0f3de8","x":290,"y":160,"wires":[["ba582285.dd04c","17d59ad8.cfa925"]]},{"id":"ba582285.dd04c","type":"debug","z":"e2a5ec72.0af0b","name":"","active":true,"console":"false","complete":"false","x":630,"y":140,"wires":[]},{"id":"17d59ad8.cfa925","type":"ui_gauge","z":"e2a5ec72.0af0b","name":"","group":"761dfbba.bd8604","order":0,"width":0,"height":0,"gtype":"gage","title":"Temperature","label":"°C","format":"{{value}}","min":0,"max":"40","colors":["#00b500","#e6e600","#ca3838"],"seg1":"","seg2":"","x":630,"y":220,"wires":[]},{"id":"86ef748c.0f3de8","type":"mqtt-broker","z":"","broker":"localhost","port":"1883","clientid":"","usetls":false,"compatmode":true,"keepalive":"60","cleansession":true,"willTopic":"","willQos":"0","willPayload":"","birthTopic":"","birthQos":"0","birthPayload":""},{"id":"761dfbba.bd8604","type":"ui_group","z":"","name":"Default","tab":"bf26a25d.84e25","disp":true,"width":"6"},{"id":"bf26a25d.84e25","type":"ui_tab","z":"","name":"Home","icon":"dashboard"}]

Control the LED based on the temperature

TODO Describe creation of the conditions with if block. Connecting the subscribe/publish

Extending to relative humidity measurement

Now we try to connect the relative humidity sensor to the Core Module. It's possible to connect the Humidity Tag directly to the Core Module as displayed in the picture (TODO) or you can use also Tag Module which can hold many more sensor tags. Also the Battery Module contains spare connector for sensor tag.

Then you can use debug nodes in Node-RED to get the right MQTT topic and copy and paste it to your new flow.

The MQTT topic will have the format node/core-module:0/hygrometer/0:2/relative-humidity.

Extending to control the relay

Now let's add the relay control. You can use Relay Module or Power Module. Connect the module to the Core Module. Based on selected module with relay you have to change the topic.

Power Module has topic node/core-module:0/relay/-/state/set

Relay Module has topic node/core-module:0/relay/0:0/state/set

Then you send true or false as a payload.

The Relay Module has also command to make a single pulse with set duration and relay direction.

Topic is node/core-module:0/relay/0:0/pulse/set and you have to publish this JSON { "duration": 500, "direction": true}. Duration is time in milliseconds.

mosquitto_pub -t "node/core-module:0/relay/0:0/pulse/set" -m "{ \"duration\": 500, \"direction\": true}"

Creation of the wireless network

Currently it is possible to create a wireless network with a star topology. The middle of the star is the device called the gateway which handles communication to all wireless nodes. Gateway can be Core Module or USB Dongle.

All other wireless devices we call as a node.

The used radio module SPIRIT is comunicating at 868 MHz frequency and with its reach will cover a larger family house and its surroundings.

Flashing gateway firmware

If you don't have USB Dongle you can use Core Module you have already connected to your Raspberry Pi. This module with already flashed firmware can act also as a wireless gateway.

If you own the USB Dongle then disconnect the Core Module from Raspberry Pi and connect the USB Dongle. Then follow next steps to flash the latest firmware. Connect the USB Dongle to the Raspberry Pi. The USB Dongle will switch to the programming mode automatically. Just execute the next command:

bcf flash --device /dev/ttyUSB0 bigclownlabs/bcf-gateway-usb-dongle:latest

Conversion to the battery operated node

BigClown building kit is from the ground-up designed for the efficient battery operation. Battery powered module with bcf-generic-node firmware will automatically scan connected sensors and modules when powered-up. In the regular intervals the measured values are sent by wireless radio to the gateway.

Place two AAA batteries to the Mini Battery Module and connect the Core Module to it.

Flashing the remote node

Upload the bcf-generic-node firmware to the remote node unit. This universal firmware contains drivers for all BigClown sensors, tags and modules. After start-up all the connected devices are automatically detected and their values are sent by wireless network to the gateway.

Connect the Core Module to the Raspberry Pi and enable the DFU flashing mode as explained in the previous chapter. Upload the generic-node with firmware-battery-mini option.

bcf flash --dfu bigclownlabs/bcf-generic-node-battery-mini:latest

In case you would power the remote note with a power adapter, you can flash power module firmware for a corresponding number of LED diodes (RGB or RGBWhite) bigclownlabs/bcf-generic-node-power-module-rgbw144:latest. This firmware is also always listening on the radio and can receive commands co control the LED pixels, relay and display the measured data on the connected LCD Module. Moreover it is possible to display custom texts on the display with various sized fonts.

List of bcf-generic-node released firmwares

Detailed flashing instructions.

Pairing process

We need to pair the gateway with the remote node. In case you are using Core Module as a gateway you can start the pairing by long press of the B button. Then the red LED will start blinking.

USB Dongle do not have pairing button and the pairing process needs to be started by a MQTT message. The same works also for the Core Module in case you cannot physically press the B button.

For USB Dongle or Core Module you need to send MQTT message with console command or by using the flow in the Node-RED which sends the pairing start message.

For USB Dongle:
mosquitto_pub -t 'gateway/usb-dongle/pairing-mode/start' -n
For Core Module:
mosquitto_pub -t 'gateway/core-module/pairing-mode/start' -n

After enabling the pairing the red LED on the USB Dongle/Core Module will start to blink. Now its the time to send pairing command from the remote node. This can be done by long press of the B button on the remote node. If you are subscribed to the # topic, you will see a message with new paired address.

Now it is possible to pair other remote nodes, just long press the B button on the other remote nodes.

After the pairing of the remotes is completed, disable the pairing process on the gateway by command:

For USB Dongle:
mosquitto_pub -t 'gateway/usb-dongle/pairing-mode/stop' -n
For Core Module:
mosquitto_pub -t 'gateway/core-module/pairing-mode/stop' -n

Measuring and controlling over radio

Remote nodes which has battery in the firmware name just transmits measured data and then they sleep. They cannot receive the commands over the wireless radio while they sleep.

Remote nodes which has power module in the firmware name are powered by power adapter or USB and can transmit measured data and also receive commands send from the gateway. Thanks to this it is possible to control practically all the connected modules over the radio:

  • Power Module - control the relay, colors and effects on the LED strip
  • Relay Module - control bistable relay with commands to toggle, switch or make a pulse
  • LCD Module - display text on the display on any position with different font sizes
  • Control red LED on the Core Module

List of all MQTT topics.

Conclusion and further steps

This tutorial explained how to lean BigClown basics with single a module connected to the Raspberry Pi. The principle is the same with other nodes which you can connect wirelessly. Now you can extend your home automation and create new rules thanks to Node-RED.