Project

General

Profile

Provisioning Sensors

The following instructions assume you have one or more sensors already connected to a BLE gateway node, and the data is being fed into MQTT. You'll need to know the MAC address of the sensor (without colons, e.g., c098e5300076) and the IP name of the BLE gateway node which runs the MQTT broker (such as uhkbbb004.eecs.berkeley.edu). Note that the MQTT to GDP gateway code generally does not run on the BLE gateway node. At the moment we are running the MQTT-GDP gateway code on the machine swarmnuc1022.eecs.berkeley.edu. To provision new sensors you have to be on that machine.

Adding a New MQTT Gateway Configuration File

If this sensor is on a new BLE gateway node, you'll have to create a configuration file for the MQTT broker corresponding to that node. These files are located in $GDP_ETC, normally /etc/gdp, /usr/local/etc/gdp, or (rarely) /usr/gdp/etc. They are always named mqtt-gateway.$shortname.conf, where $shortname is the name of the host with the MQTT broker without any dots (e.g., uhkbbb004 rather than uhkbbb004.eecs.berkeley.edu). Text between a hash mark (#) and the end of the line is ignored (comment) and empty lines (white space only) are ignored.

The first line is the root name of the logs to be written for this broker, generally based on the physical location of the log and using the reversed-domain convention, e.g., edu.berkeley.eecs.bwrc. To this root name, .device.$devname is appended, where $devname is the name of the device in reduced MAC address format (e.g., c098e5300009). Each device has its own log.

For example, a MQTT gateway configuration named mqtt-gateway.uhkbbb004.conf could read:

# BWRC server room, uhkbbb004, 128.32.63.176
edu.berkeley.eecs.bwrc
c098e5300009    # BLEE, lab rear wall
c098e5300036    # BLEE, rear wall
c098e5300054    # BLEE, hot aisle
c098e530005d    # BLEE, mid wall
#c098e5700089   # Power Blade (not listed on wiki page; "backup"???)
c098e570008f    # Power Blade, sump pump
c098e5700090    # Power Blade, air compressor
c098e590001e    # Blink

This would append to logs named edu.berkeley.eecs.bwrc.device.c098e5300009 etc. Note that these logs are not automatically created. A typical use case might be to create the configuration file with the log root name only and then proceed to the next step to provision individual sensors.

If you are on a system running systemd you will also have to create an "instance" for the system startup. You can do this using systemctl:

systemctl enable mqtt-gdp-gateway@uhkbbb004.eecs.berkeley.edu

If you are using upstart you'll need to edit /usr/sbin/start-mqtt-gdp-gateways.sh and add the appropriate $START line (the syntax should be obvious).

Provisioning a New Sensor for an Existing MQTT-GDP Gateway

New sensors can be added to an existing MQTT-GDP gateway configuration using the gdp-provision-sensor script:

gdp-provision-sensor mqtt-broker-name sensor1 sensor2 ...

You'll need to run this as user gdp or root (which will switch to gdp).

The config-name is the host name corresponding to the configuration file (uhkbbb004, uhkbbb004.eecs.berkeley.edu, and /etc/gdp/mqtt-gateway.uhkbbb004.conf all work). The sensors are the MAC addresses for individual sensors. These will be massaged into the correct format; for example, C0:98:35:90:00:1E will be translated to c098e590001e.

For each sensor listed the script will:

  1. Verify that the sensor is not already configured.
  2. Create the necessary log if it does not already exist.
  3. Add the sensor to the configuration.

You can add comments to the configuration file later if desired.

Removing Sensors

There is no automated procedure to take a sensor out of service. Hand edit the configuration file and delete or comment out the line naming the sensor to be removed. If you are eliminating a gateway entirely, use systemctl disable mqtt-gdp-gateway@uhkbbb004.eecs.berkeley.edu or comment out the $START line in /usr/sbin/start-mqtt-gdp-gateways.sh.