How to connect an actual (hardware) iot device to FIWARE Orion Context via the IoT Agent for JSON

Question

Is there any tutorial or guide to follow and connect a hardware IoT Device via the IoT Agent for JSON? All the tutorial are working just fine with the virtual provisioned devices but there is no reference on how to proceed and connect an actual device.

I have tried the tutorial (https://github.com/FIWARE/tutorials.IoT-Agent-JSON) with success but I do not know how to connect lets say an actual smart lamp.

Answer 1

The tutorial app creates dummy devices which are capable of sending a payload over HTTP or MQTT

// measures sent over HTTP are POST requests with params
sendAsHTTP(deviceId, state) {
    const options = {
        method: 'POST',
        url: IOT_AGENT_URL,
        qs: { k: getAPIKey(deviceId), i: deviceId },
        headers: this.headers,
        body: state
    };
    const debugText = 'POST ' + IOT_AGENT_URL + '?i=' + options.qs.i + '&k=' + options.qs.k;

    request(options, (error) => {
        if (error) {
            debug(debugText + ' ' + error.code);
        }
    });
    SOCKET_IO.emit('http', debugText + '  ' + state);
}

// measures sent over MQTT are posted as topics 
sendAsMQTT(deviceId, state) {
    let topic = '/' + getAPIKey(deviceId) + '/' + deviceId + '/attrs';
    if (process.env.MQTT_TOPIC_PROTOCOL !== '') {
        topic = '/' + MQTT_TOPIC_PROTOCOL + topic;
    }
    MQTT_CLIENT.publish(topic, state);
}

Any real device would also need to follow these steps, so for example looking in the Arduino Documentation you can program a device to emit on a chosen MQTT topic.

The same technique can be used for actuation. Either get the device to listen on HTTP:

if (DEVICE_TRANSPORT === 'HTTP') {
    debug('Listening on HTTP endpoints: /iot/bell, /iot/door, iot/lamp');

    const iotRouter = express.Router();

    // The router listening on the IoT port is responding to commands going southbound only.
    // Therefore we need a route for each actuator
    iotRouter.post('/iot/bell:id', Southbound.bellHttpCommand);
    iotRouter.post('/iot/door:id', Southbound.doorHttpCommand);
    iotRouter.post('/iot/lamp:id', Southbound.lampHttpCommand);
    iotRouter.post('/iot/robot:id', Southbound.robotHttpCommand);
    // Dummy ISOBUS/ISOXML endpoint.
    iotRouter.post('/iot/isoxml', Southbound.isobusHttpCommand);

    iot.use('/', iotRouter);
}

Or subscribe to a given MQTT topic:

if (DEVICE_TRANSPORT === 'MQTT') {
    const apiKeys = process.env.DUMMY_DEVICES_API_KEYS || process.env.DUMMY_DEVICES_API_KEY || '1234';

    MQTT_CLIENT.on('connect', () => {
        apiKeys.split(',').forEach((apiKey) => {
            let topic = '/' + apiKey + '/#';
            if (process.env.MQTT_TOPIC_PROTOCOL !== '') {
                topic = '/' + MQTT_TOPIC_PROTOCOL + topic;
            }
            debug('Subscribing to MQTT Broker: ' + MQTT_BROKER_URL + ' ' + topic);
            MQTT_CLIENT.subscribe(topic);
            MQTT_CLIENT.subscribe(topic + '/#');
        });
    });

    mqtt.connect(MQTT_BROKER_URL);

    MQTT_CLIENT.on('message', function (topic, message) {
        // message is a buffer. The IoT devices will be listening and
        // responding to commands going southbound.
        debug('MQTT message received on', topic.toString());
        Southbound.processMqttMessage(topic.toString(), message.toString());
    });
}

Of course this example is for JSON or Ultralight payloads, other protocols would need to connect to the appropriate middleware (e.g. an OPC-UA device connecting to an OPC-UA server), however in general your device will be able to download an appropriate comms library and you'll need to code up the set-up and measure rate and/or actuation response using the language found on the device itself - the Arduino docs are using C++ for example.