Gateways and Peripherals

Some types of devices, like Bluetooth sensors, cannot connect directly to WEGnology. They require some form of middle man in order to communicate externally. In order to facilitate this, WEGnology has the concept of Gateway and Peripheral devices. Gateway devices are permitted to report state and receive commands on behalf of Peripheral devices.

Gateways

Gateways are very similar to regular devices. They connect directly to WEGnology and can report their own state and receive commands. The only difference is that gateways are allowed to report state for other peripheral devices.

A basic gateway device is created by choosing the the Gateway device type when adding a new device. For more advanced use cases, devices of the Edge Compute device type can also function as gateways.

When viewing a Gateway or Edge Compute device, a list of all Peripheral devices associated that device are available under the “Peripherals” tab. This list does not include any “floating peripherals” (those that allow “Any Gateway” to report on its behalf).

Peripherals

Unlike regular devices, peripherals do not connect directly to WEGnology. They are typically connected to a Gateway using something like Bluetooth. How a peripheral is actually connected to a gateway is entirely up to your specific environment.

Peripherals are created by choosing the Peripheral device type when adding new devices.

You can then decide if the peripheral device should be allowed to report its state through any gateway within the application, or if state reporting should be restricted to only a particular gateway. “Any Gateway” is generally used for peripheral devices that move, and so might switch between statically located gateways at multiple locations. “Specific Gateway” is generally used for a peripherals that are attached to a single gateway, perhaps even actually physically attached.

Reporting State for Peripherals

Once a gateway and one or more peripherals are created, it’s now up to the gateway to report state on behalf of the peripheral whenever required. In order to accomplish this, gateways are simply permitted to publish and subscribe to a peripheral’s MQTT topics and POST to a peripheral’s REST endpoints. These requests can be done over the gateway’s connection and using the gateway’s authentication tokens. Below are a few examples.

A gateway can publish state for itself by publishing to its own MQTT state topic:

wegnology/my-gateway-id/state

A gateway can also publish to a peripheral’s MQTT state topic:

wegnology/my-peripheral-id/state

A gateway can subscribe to its own MQTT command topic:

wegnology/my-gateway-id/command

A gateway can also subscribe to any peripheral’s MQTT command topic:

wegnology/my-peripheral-id/command

A gateway can POST its own state using REST to the following endpoint:

/applications/my-application-id/devices/my-gateway-id/state

A gateway can also POST to a peripheral’s REST state endpoint:

/applications/my-application-id/devices/my-peripheral-id/state

Please refer to the MQTT and REST documentation for further details on the format of these requests.

Below is an example of how to use the Node.js MQTT module to connect as a gateway and publish state for a peripheral.

var mqtt = require('mqtt')

// Connect to WEGnology as the Gateway.
var client = mqtt.connect('mqtts://broker.app.wnology.io', {
  clientId: 'my-gateway-id',
  username: 'my-access-key',
  password: 'my-access-secret',
})

client.on('connect', function() {
  // Example peripheral state. Typically this would come over some
  // remote connection, like Bluetooth.
  var peripheralState = { data: { temperature: 72 } }

  // Publish state for the peripheral.
  client.publish('wegnology/my-peripheral-id', JSON.stringify(peripheralState))
})

When and how a gateway publishes these message is entirely up to your environment. For example, if the peripheral is a LightBlueBean connected over Bluetooth to a Raspberry Pi gateway, the Pi may report the peripheral’s state every few seconds by first requesting the temperature over the Bluetooth connection.

Gateways can also be used to configure MQTT bridges.

To the rest of the system, there’s no difference between a gateway reporting state on behalf of a peripheral versus a device reporting state directly. You can now visualize the data, trigger workflows, etc.