QNX Agent

Synchronize the selected PPS objects to the BlackBerry IoT Platform

To get access to the QNX Agent, contact a representative from our sales team.

Syntax:

bipd [-C CONFIGFILE]

Runs on: QNX Neutrino RTOS

Options:

-C CONFIGFILE: Use CONFIGFILE as the configuration file. The default is /var/bipd/config.

Description:

The QNX Agent reads the PPS objects on your QNX system and synchronizes them with the BlackBerry IoT Platform. The QNX Agent runs as a daemon (bipd) on your physical device, and converts the selected directories in the /pps directory tree to corresponding state objects for the device on the BlackBerry IoT Platform.

To use the QNX Agent, your device must be using QNX Neutrino and Persistent Publish/Subscribe (PPS). Create an application and device entities on the BlackBerry IoT Platform, and download the API KEY and API SECRET. This information must be listed in the configuration for QNX Agent.

The Configuration File:

The configuration file contains the following JSON-encoded settings:

url: Base URL for the BlackBerry IoT Platform, such as https://bbryiot.com/.

auth_url: Authentication URL for the BlackBerry IoT Platform, such as https://auth.bbryiot.com/.

secretsfile: The file containing the API key and secret, one per line, in that order. These are properties of the application this device belongs to, and are the same for all devices of this application. This information can be copied from the administration console (double-click the application and then click the Keys/Secrets button). The secrets file must have mode 0400 or the daemon fails to start.

keyfile: The file containing the private key for this device in PEM format (beginning with -----BEGIN PRIVATE KEY----- followed by a block of base64-encoded data).

certfile: The file containing the certificate for this device (beginning with -----BEGIN CERTIFICATE----- followed by a block of base64-encoded data).

log_level: The maximum level that will be logged. Logs on QNX platforms are directed to slogger, and syslog for Linux. Valid interger values can be found in the bip_log_level_t enum in bb/iot/bip.h. By default this value is set to 2.

persistence_path: The location where the agent should save any persisted requests. If ommitted requests are not persisted and will be lost when the agent exits. It is important that this path be set to a QNX 6 file system path. The binary must also have read/write permission on this directory.

persistence_size: The maximum size, in Megabytes, for persistence. By default this property is set to 0, which makes the persistence size unbounded.

encoding: The encoding for post data and responses from the remote server. Valid values are "identity" and "deflate". By default this value is set to "defalte".

error_timeouts: An array of integers, which represents the timeout in seconds, for when to retry a request when a 500 error is returned from the server. If ommitted, the agent will retry in 1 minute.

notifications: The notifications filter to use. For more information, see the REST API documentation.

authentication: A JSON object for authentication configuration options.

sync: A JSON object that specifies the PPS paths to synchronize to the cloud when they change.

logs: A JSON array of that specifies the log components and levels to synchronize to the cloud.

Each logs object in the array can have three properties:

For example, a configuration file might look like:

{
    "url": "https://bbryiot.com",
    "auth_url": "https://auth.bbryiot.com",
    "secretsfile": "/etc/bipd/app_secrets",
    "keyfile": "/etc/bipd/private_key",
    "certfile": "/etc/bipd/certificate",
    "log_level": 3,
    "notifications":{"data_filters":[],"message_filters":[]}
    "sync": {
        "paths":[
            {
                "path": "/pps/country",
                "id": "location"
            },
            {
                "path": "/pps/logs/*",
                "id": "slog",
                "category": "log"
            },

                "path": "/pps/versions/*",
                "id": "",
                "category": "component"
            }
        ]
    }
}

The certificate file and private_key file (called /etc/bipd/certificate and /etc/bipd/private_key, respectively are PEM-encoded files. The application secrets file (called /etc/bipd/app_secrets in the example), might contain:

Xe1I_2heI1dY0PbsxPBzb-5vXWYF9M0W
nc7FheJtKR+93IeXYL1vTr4aWbmkn7H7pCq505GPLts=

Incoming Messages

Incoming messages are written to /pps/bipd/msg/inbox/<message type>/<message UUID>. Clients can monitor for new messages of a specific type by opening /pps/bipd/msg/inbox/<message type>/.all?wait. After a file is created in the parent directory, its content contains all of the properties of the message. After you have processed the message, you can remove the file to delete it from the cloud.

Sending Messages

A PPS message, formatted in the following way, can be sent to /pps/bipd/msg/.out to send a message.

msg::send
dat:json:{"type":"msg_type","target_id":"some device id", "data":{"prop":"value"}}
id::1234

If an idproperty is provided, the server returns the following response after the message has been sent:

res::send
dat:json:{"id":"UUID of the message"}
id::1234

If there was an error, the response contains err and errstr properties. If the server returns a successful response, the msg properties are written to the /pps/bipd/msg/outbox/<UUID> object, where <UUID> is the id that was returned in the dat object of the response.

Uploading Files

A PPS message, formatted in the following way, can be sent to /pps/bipd/files to upload a file.

msg::send
dat:json:{"path":"path/to/file", "deleteOnComplete":true, "data":{"description":"A new file", "metadata":{"prop":"value"}}}
id::1234

If an idproperty is provided, the server returns the following response after the message has been sent:

res::send
dat:json:{"id":"UUID of the file"}
id::1234

If there was an error, the response contains err and errstr properties.

Device Data

The plugin_data_jps.so plugin provides a JAM connection at /jam/bipd/data, which supports messages related to device data. The /jam/bipd/data path must exist before the agent is started.

Data Updates

An update message can be sent to the JAM connection to update device data in the cloud. The JSON payload for the message should be formatted in the following way:

[
    {
        "id": "location",
        "category": "state",
        "values": {
            "lat": 45.343665,
            "long": -75.909638
        },
        "realtime": false
    }
]

The payload can have any number of objects in the array, with the following format:

A flush message can be sent to the JAM connection to send buffered data to the cloud. This makes it easy for clients to send an update message where realtime is set to false, and then send a flush message to send the buffered updates to the cloud.

Data Reads

A read message can be sent to the JAM connection to get device data from the cloud. The JSON payload for the message should be formatted in the following way:

{
    "id": "location",
    "category": "state"
}

The response to the message will contain the id, category, and values properties of the data in a JSON string, such as:

{
    "id": "location",
    "category": "state",
    "values": {
        "lat": 45.343665,
        "long": -75.909638
    }
}