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.

Device API¶

API Call Reference¶

Generic Task JSON Considerations¶

Task definitions¶

Task reload¶

Task upgrade¶

Task ipquality_destination¶

Task ipquality_source¶

Task license¶

Task csp¶

Table of Contents

Related Topics

API email update