Broox Sensor Node

Required Platform

A running install of Broox Controller.
Ubuntu Linux 18.04 or Windows 10.
A copy of Broox Sensor Node installer package.

Installing the Sensor Node

Windows

Download Broox Sensor Node X.X.X.exe or the combo BrooxPlatform-X.X.exe installer
Double click on the installer and follow the screens.
Check if you want a desktop launcher icon.
Continue the installation clicking Next, Next. Wait for the installer to finish.
Close the installer.
You can now launch Broox Sensor Node from the Start Menu (or desktop icon if you selected it).

Linux

Download broox-sensor-node_X.X.X.amd64.deb
Open the Terminal. cd to the Download folder.
Install using apt:

    sudo apt install ./broox-sensor-node_X.X.X.amd64.deb

Start by executing:

     /opt/broox/BrooxSensorNode/BrooxSensorNode

Configuring

Expand the Configuration section (click on the rightmost little arrow button, not start).
Select the Controller first, and then you can add sensors.
For example, select the Nexmosphere Sensor from the Add Sensor dropdown.
Press Add.
Select the Port the Nexmosphere controller is plugged into (COMX: on windows, /dev/ttyUSBX on Linux).
You can add several sensors.
Press Start to start receiving and sending messages to and from them.
You can delete a sensor by pressing Delete.

Note that you'll need at least one sensor to do something useful.

Sensors

Sensors in the Broox Sensor Node use a common trigger message format.

The message is sent over MQTT in the common form used by Broox Controller.

Different types of sensors are supported:

All use the common Trigger Message

{ "cmd": "trigger", "class": "<class>", "action": "<action>", "id": "<trigger-id>", … extra attributes...
  "origin":  {
    "type": "<sensor-type>",
    "address": "<com port + subport>",
    "class": "<sensor-class>
  }
}

cmd is always trigger
class depends on the sensed item: Can be rfid or onevent (generic).
action is normally in or out
id is the identifer of the sensed item: the RFID tag, some configured tag (car, mouse, ...).
Extra attributes
origin identifies the sending sensor:
- type will usually be the generic kind or manufacturer: xtalk, serial, maxbotix...
- address can be the COM port or any subport info (for talk can be the bus address)
- class is the internal name of the sensor (XRDR1, Serial, ...)

RFID Sensors

RFID Sensors are supported right-on by Broox Studio to trigger events. They have class=rfid.

The common form uses an action = in or out and the id field contains the RFID ID Value.

That can be an HEX field 0a:0b:fa:23:... or a provider-specific one (like nexmos-1).

{ "cmd": "trigger", "class": "rfid", "action": "in", "id": "nexmos-1", 
  "origin":  {
    "type": "xtalk",
    "address": "3",
    "class": "XRDR1"
  }
}

Distance/Zone Sensors

Distance sensors come in a variety of forms: ultrasound, laser, infrared,... Some give a metric distance reading, others just a in/out of range signal.

The common form uses the generic class=onevent form, with an action of in or out depending on obstacle detection.

To ease identification, each sensor can also contain a zone field (string). Depending on the model, extra attributes can be added.

{ "cmd": "trigger", "class": "onevent", "action": "in", "id": "xeye-1", "zone": 5, 
  "origin":  {
    "type": "xtalk",
    "address": "4",
    "class": "XEye"
  }
}

Button Sensors

The common form uses the generic class=onevent form, with an action of in on button press.

Configuring sensor parameters

Sensor parameters can be fine-tuned by editing the sensor.ini file. This allows to change, for example, the zone of detection trigger, the COM port, etc. To edit the sensor.ini file, expand the Configuration section of the Sensor Node GUI and click on Edit sensor.ini

This will open the built-in text editor, you can alter the settings and save via the menu or Ctrl+S/Cmd+S.

Restart the Sensor Node after editing to apply the new settings.

Example sensors

Nexmosphere Sensor and Actuators

The Nexmosphere Suite of Sensor Devices is supported partially by the Sensor Node.

RFID Sensor (XRDR1)

The Nexmosphere RFID sensor recognizes up to 20 tags. Those tags will be identified by the string "nexmos-X" where X is the number on the tag (e.g. nexmos-8, nexmos-18…)

The actions the RFID triggers on pick up are defined in the Broox Studio.
On put back the reverse (return to idle) action is triggered.

You should define the triggers (if not already present) in the Installations/Triggers/RFID section on the Studio.

Triggers Section

If the required RFID is not present, you can create it by:

Clicking on Add RFID.
Entering nexmos-X as the ID (where X is the tag number on the sticker).
In RFID, you can type a name for it.

Lift & Learn vs. Place & Learn

The default experience is a Lift&Learn experience. Several products are on the antenna(s) and you grab one.

To create a Place&Learn experience, where you put a product on the antenna one by one, we need to reverse the pick up and put back messages:

Open the Sensor Node configuration UI.
Edit the sensor.ini file.
On the [xtalk] section add/uncomment the line xrdr-invert = true.
Restart the Sensor Node.

XEye Presence Sensor

By default the presence sensor emits a custom trigger of type onevent*, action in, and a value zone from 0 to 10, as defined in the Nexmosphere XEye manual (each "zone" is a distance range).

    {"cmd": "trigger", 
    "class": "onevent", 
    "action": "in", 
    "zone": 5,
    "origin": { "type": "xtalk", "port": 3, "class": "XEye" }...}

The default zone is 5, to change it you have to edit the sensor.ini file and uncomment and change the xeye-trigger-at value.

[sensor:1]
name=Nexmosphere Xtalk Sensor/Actuator
backend=xtalk
;; Serial port to use
port=COM2:
;; Baudrate
baudrate=115200
;; Xeye trigger distance. Set a value from 1 to 9.
;; See the Xeye manual for distance metrics of the different zones.
xeye-trigger-at=3
;;

LightMark Devices

LighrMark devices control LED light strings.

The LightMark devices do not support automatic discovery, so they have to be hardcoded in the sensor.ini file.

For example, if the Nexmosphere ID where the strings are connected are numbered from 111, to 114, the staticmap line in sensor.ini reads:

;; Static device map:

;; A list of device-index:device-type separated by commas

;; This devices will be created on startup

staticmap=111:LightMark,112:LightMark,113:LightMark,114:LightMark

This will create the mapping, and you can address the different LightMark devices via its number (111 to 114).

Arduino and simple serial devices

Simple serial devices just read the given serial port and wait for a "number" (+CRLF) line to be read, and generate a trigger event when the value is over a threshold.

... reading com port
0
0
0
1  => Triggers event  
1
1
1
0

By default, a value of 1 will do.

Adjust the baudrate=9600 for the COM port and the threshold=1 in the sensor.ini to use other values than the default.

[sensor:0]
name=Simple Serial Sensor
backend=serial
port=COM1:
baudrate=9600
threshold=1

Broox Controller Custom Rules

To control interactions, apart from the triggers in the CMS you can use custom rules in the Broox Controller.

Those are defined in a rules.json file, referenced in controller.ini.

...
[rules]
extra=rules.json
...

The format of the rules follows the WHEN event IF conditions THEN actions form.

"rules" : 
[
    {
        "comment" : "Some comment",
        "event" : "trigger",
        "conditions" : [
            ["event.payload.class", "==", "onevent"],
            ["event.payload.action", "==", "in"],
            ["event.payload.origin.class","==", "XEye"]
        ],
        "actions" : [
            {"command" : "devices",
             "arguments" : ["send", "event.origin", "actuate", "target", "LightMark-113", "action", "ramp", "args", "[90,3,30]"]
            }, ...
        ]
    }, ...
]

You can edit the rules to change the target to LightMark-XXX (whatever ID you want), the action (ramp) or the parameters to ramp (args).