Device API

API Call Reference

POST /api/device/session

Create and authenticate a session object with the specified device.

Request body example

{
    "device": "dc7d3012-7736-11e1-8a6d-0024e8f90cc0",
    "key": "dijaDia8Aiofjb9aaobasdfDF",
    "hw_version": "cospace-box",
    "sw_version": "001",
    "ip_addr": "212.202.0.10",
    "mac_addr": "00:24:d6:83:c1:54",
    "timeout": 15
}
JSON Parameters:
 
  • device

    UUID

    The UUID of the physical device

  • key

    ^.{5,50}$

    The authentication key of the device (plain-text)

  • hw_version

    ^.{1,20}$

    The hardware version / model of the device

  • sw_version

    ^.{1,20}$

    The currently running software version on the device

  • ip_addr

    IP address

    The current IP address of the device

  • mac_addr

    ^[0-9a-f]{2}(:[0-9a-f]{2}){5}$

    The current MAC address of the device

  • timeout

    15-1000

    Optional: the timeout for the GET /api/device/task call

Response body example

{
    "sid": "boajw93bawjckbja2ZdbfdGa84Afib",
    "server": "https://api43.service.de:1234",
    "timeout": 15
}
Status:
  • wrong-auth: device or key are invalid.

This command creates a new device session. Device sessions are used to communicate between physical devices (“cospace box”) and the cospace cloud. If a new device session is established, an existing session towards this device that might exist is closed.

Further API calls that reference this session can only be made towards the server specified in the server field, as the session state is only maintained on this server.

The timeout field informs the client about the response timeout for the GET /api/device/task call.

DELETE /api/device/session

Closes a device session and invalidates the corresponding session id.

Response body example

{}

After closing the session, the session id is deleted on the server and can not be used for any further requests.

POST /api/device/csp

Inform the system of a cospace sensor protocol (cSP) payload packet

Request body example

{
    "packet": "wqc4bHc3ZW5kOC85NGlha0Nvc0VxK2YjKjQ5MiYyIQo=",
    "time": 1320403260,
    "rssi": -80,
    "lqi": 45
}
JSON Parameters:
 
  • packet

    ^.{10,500}$

    The complete cSP packet (excluding preamble, sync word and CRC field), as a base64 encoded string

  • time – The time of packet reception in seconds-since-epoch
  • rssi – The received signal strength indication in dBm
  • lqi – The link quality indication, higher value means better signal

Response body example

{}

If a devices receives a valid (i.e., the CRC is correct) cospace sensor protocol message, this API call is used to inform the system about this packet.

GET /api/device/task

Requests the list of open tasks for the device

Query Parameters:
 
  • next – optional: the id of the first task to be returned (default: 0)

Response body example

{
    "task": [
        {
            "id": 1,
            "task": "ipquality_source",
            "time": 2182782732,
            "remote": "212.202.3.45",
            "port": 4711,
            "duration": 10
        },
        {
            "id": 2,
            "task": "ipquality_destination",
            "time": 2182782733,
            "duration": 10
        }
    ]
}

This API call is the way tasks are delivered to devices. A device is expected to repeatedly call this function in order to receive all tasks scheduled for it. See Generic Task JSON Considerations for details about the individual tasks.

A call to this API may block for some time, if there are no tasks in the queue with id equal or greater than the given next parameter. The maximum wait time is announced to the client in the POST /api/device/session call.

The list of tasks may be empty if no tasks were scheduled and the (server-defined) blocking time is reached.

POST /api/device/task/(task-id)

Deliver a response to the requested task task-id

Query Parameters:
 
  • intermediate – optional: if present, signals an intermediate response. In this case, a final response (without the intermediate flag) will follow later.

Response body example

{}
Status:
  • wrong-task: The task with the specified task-id does not exist in the server’s task list

The content of the request body is task-specific and is defined with the respective task in chapter Task definitions on page 252.

Generic Task JSON Considerations

Each task (as returned with the GET /api/device/task call) has a specific JSON representation that is defined in the following sections. Besides the specific elements, there is also a common structure, i.e. some fields that are present in all tasks. The generic JSON representation of any task („task skeleton”) looks like this:

{
    "id": 42,
    "task": "ipquality_source",
    "time": 2182782732
}

The id field is a unique identifier of the task in the context of the current device session. The first task of a newly created session has id 0, and the id is increased by 1 with every new task. This enables a client to detect whether the stream of tasks in contiguous. The time field lists the time of event generation in seconds-since-epoch.

Task definitions

Task reload

Instructs the device to perform a reboot. If the force option exists and is set to true, the device should reboot immediately, without going through the various system shut-down routines and sending a response to this task (e.g. by directly calling the reboot(2) system call).

Task example (JSON)

{
    "force": false
}

Final response example (JSON)

{
    "status": "ok"
}

If a forced reboot is requested, the device will not send a response to this task. Otherwise, it will send the response before starting the reboot sequence.

If a response is sent and the status field does not contain ok, a message field should also be present describing the specific failure.

Task upgrade

Instructs the device to perform a software upgrade.

The device must downloaded all software components from the given volume. When a device gets the upgrade task, it is permitted to access the given volume read-only. The volume should contain a number of first-level sub-folders, called batch01, batch02, and so on. For each sub-folder, the device will

  • create a local, temporary directory
  • download all files from the given sub-folder to the temporary directory
  • execute /bin/sh ./run.sh within the temporary directory
  • remove the temporary directory and all files within it

This mechanism allows software upgrades to be performed in multiple batches that will be run in a defined order (e.g., to cope with memory restrictings on the device).

Task example (JSON)

{
    "volume": "7fc63784-b39e-11e1-80cc-0024e8f90cc0"
}

Intermediate response example (JSON)

{
    "status": "ok",
    "batch": 1
}

Final response example (JSON)

{
    "status": "ok"
}

For each batch that was executed, the device will send an intermediate response containing the batch number.

If a response or intermediate response is sent and the status field does not contain ok, a message field should also be present describing the specific failure.

However, it depends on the upgrade procedure whether the device will send intermediate or final responses at all. For example, if the upgrade process reboots the device, responses might not be reliable.

Task ipquality_destination

Instructs the device to start the passive (receiving) side of an IP quality measurement.

The duration field contains the duration of the measurement.

The device will send an intermediate response as soon as the receiving side is ready, and include both the device-local IP-address (remote) and port. This information is used by the server to setup the active (sending) side of the IP quality measurement afterwards.

Task example (JSON)

{
    "duration": 10,
    "dscp": 46,
    "ptime": 20,
    "psize": 200
}

Intermediate response example (JSON)

{
    "remote": "212.202.32.5",
    "port": 4711
}

Final response example (JSON)

{
    "p_s": 500,
    "p_r": 480,
    "t_n": 475,
    "t_min": 13,
    "t_max": 56,
    "t_sum": 14970,
    "t_sq": 311875,
    "j_n": 465,
    "j_max": 34,
    "j_sum": 2413,
    "j_sq": 11625
}

Explanation of fields in the response:

p_s: number of packets sent

p_r: number of packets received

t_n: number of packets valid for RTT (round-trip time) calculation

t_min: minimum RTT (ms)

t_max: maximum RTT (ms)

t_sum: sum of all RTT values of valid packets (ms)

t_sq: sum of all squared RTT values of valid packets (ms^2)

j_n: number of packets valid for jitter calculation

j_max: maximum jitter (ms)

j_sum: sum of all jitter values of valid packets (ms)

j_sq: sum of all squared jitter value of valid packets (ms^2)

Task ipquality_source

Instructs the device to start the active (sending) side of an IP quality measurement.

The duration field contains the duration of the measurement. The measurement should start immediately against the passive side (IP address remote and port) after the device receives this task.

Task example (JSON)

{
    "remote": "212.202.32.5",
    "port": 4711,
    "duration": 10,
    "dscp": 46,
    "ptime": 20,
    "psize": 200
}

Final response example (JSON)

{
    "p_s": 500,
    "p_r": 480,
    "t_n": 475,
    "t_min": 13,
    "t_max": 56,
    "t_sum": 14970,
    "t_sq": 311875,
    "j_n": 465,
    "j_max": 34,
    "j_sum": 2413,
    "j_sq": 11625
}

Explanation of fields in the response:

p_s: number of packets sent

p_r: number of packets received

t_n: number of packets valid for RTT (round-trip time) calculation

t_min: minimum RTT (ms)

t_max: maximum RTT (ms)

t_sum: sum of all RTT values of valid packets (ms)

t_sq: sum of all squared RTT values of valid packets (ms^2)

j_n: number of packets valid for jitter calculation

j_max: maximum jitter (ms)

j_sum: sum of all jitter values of valid packets (ms)

j_sq: sum of all squared jitter value of valid packets (ms^2)

Task license

Informs the device about the license status of the associated box object.

If there is a license, the task carries the license key in the license field.

If the license is present and valid, the valid field will have the value true, and false if not.

Task example (JSON)

{
    "license": "EXAMP-LELIC-ENSEK-EY007",
    "valid": true
}

Final response example (JSON)

{}

Task csp

Informs the device to send out a message in the cospace sensor protocol (cSP).

The csp_xxx fields represent the respective fields within the cSP. The csp_payload field contains the payload section of the cSP packet as a base64 encoded string. If wait_recv is present and true, it informs the device to first wait for a transmission from the sensor before sending out the packet. If in addition wait_timeout is present, it is a hint for the device to set the timeout waiting for a transmission from the sensor.

Task example (JSON)

{
    "wait_recv": true,
    "wait_timeout": 30,
    "csp_proto_type": 0,
    "csp_address": "013a5e7f",
    "csp_packet_id": 7,
    "csp_time": 1363790008,
    "csp_payload": "wqc4bHc3ZW5kaWE0OTImMiEK"
}

Final response example (JSON)

{
    "status": "ok",
    "rssi": -80,
    "lqi": 45
}

The device will send a response when the sensor has confirmed the reception of the message (for message types that require acknowledgement) or when the message has been sent out (for message types that do not require acknowledgement).

If status contains replaced, this indicates that the cSP message has been superseded by another message while still waiting for the sensor to transmit.

If the status field does not contain ok or replaced, a message field should also be present describing the specific failure.

If the sensor confirmed the reception of the packet, the final response will contain the rssi and lqi fields to signal the received signal strength indication (in dBm) and the link quality indication (higher value means better signal) of the acknowledgement packet.