Skip to content

OTAC API

The Over-the-air configuration (OTAC) API provides programmatic access to the Veva III allowing developers to integrate the device into their own software platforms. The API provides remote configuration, updating and status checks of the Veva III.

Info

The OTAC API is only available when using cellular service provided by Inzwa. When using your own cellular service or a WiFi module, please use MQTT.

Base URL

The base URL for all requests is: 

https://api.inzwa.cloud

API Version

The OTAC API exposes different versions of the API. The current version of the api is available by specifying latest in the request path: 

https://api.inzwa.cloud/latest

Alternatively, you can specify a version using the version number in the request path: 

https://api.inzwa.cloud/{version}

API Versions

Version Status Latest
latest Available Y

API Authentication

The OTAC API uses an authentication key to grant access. If your organization hasn't been provided with a key, please contact Inzwa.

The API key must be provided in a x-api-key header with each request. Please see the code examples below for more details.

API Resources

sendCommand

GET /veva3/sendCommand?deviceId={deviceId}&cmd={command}

Sends an M2M (SMS) command to the device. The available commands are found in the Command Reference section. The API will respond with:

{
  'status': 'queued'
}

on success or an error message. To see the response to your command, use the getCommandHistory endpoint.

Query Parameters

Parameter Required Description
{deviceId} Y Serial number of Veva III.
{command} Y Command to send to Veva III. Available commands are found in the command reference.

Example Requests

curl --request GET \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --url 'https://api.inzwa.cloud/latest/veva3/sendCommand?deviceId=abc123&cmd=stat%20get'

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.inzwa.cloud/latest/veva3/sendCommand',
  qs: {deviceId: 'abc123', cmd: 'stat get'},
  headers: {'x-api-key': '<YOUR_API_KEY>'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import http.client

conn = http.client.HTTPSConnection("api.inzwa.cloud")

payload = ""

headers = { 'x-api-key': "<YOUR_API_KEY>" }

conn.request("GET", "/latest/veva3/sendCommand?deviceId=abc123&cmd=stat%20get", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

getCommandHistory

GET /veva3/getCommandHistory?deviceId={deviceId}&limit={number}

Returns a JSON array of command history objects containg a reverse chronological list of M2M (SMS) commands sent to and from the device.

Query Parameters

Parameter Required Description
{deviceId} Y Serial number of Veva III.
{number} N Number of historic commands to return. Defaults to 20

Example Requests

curl --request GET \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --url 'https://api.inzwa.cloud/latest/veva3/getCommandHistory?deviceId=abc123&limit=4'

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.inzwa.cloud/latest/veva3/getCommandHistory',
  qs: {deviceId: 'abc123', limit: '50'},
  headers: {'x-api-key': '<YOUR_API_KEY>'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import http.client

conn = http.client.HTTPSConnection("api.inzwa.cloud")

payload = ""

headers = { 'x-api-key': "<YOUR_API_KEY>" }

conn.request("GET", "/latest/veva3/getCommandHistory?deviceId=abc123&limit=50", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Example Response

[
  {
    "id": "DC838e4fc62a69f6418e515828d02ffcf2",
    "command": "Peak file dump in progress",
    "status": "received",
    "direction": "from_sim",
    "dateCreated": "2019-05-20T13:17:25.000Z"
  },
  {
    "id": "DCa460d5774f8116479be006060d36be89",
    "command": "peak snap",
    "status": "delivered",
    "direction": "to_sim",
    "dateCreated": "2019-05-20T13:17:17.000Z"
  },
  {
    "id": "DC575bd4c5bebdb4cccdfdb8951136179e",
    "command": " MAC:abc123 - Ver 2.0.21 - Up",
    "status": "received",
    "direction": "from_sim",
    "dateCreated": "2019-05-20T12:28:34.000Z"
  },
  {
    "id": "DC4db48d867eb8143ab76a8b6cc07c27d8",
    "command": "reset abc123",
    "status": "delivered",
    "direction": "to_sim",
    "dateCreated": "2019-05-20T12:27:15.000Z"
  }
]

getDeviceConfig

GET /veva3/getDeviceConfig?deviceId={deviceId}

Returns a device config JSON object containing a complete list of the device's configuration parameters and values.

Query Parameters

Parameter Required Description
{deviceId} Y Serial number of Veva III.

Example Requests

curl --request GET \
--url 'https://api.inzwa.cloud/latest/veva3/getDeviceConfig?deviceId=abc123' \
--header 'x-api-key: <YOUR_API_KEY>'

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.inzwa.cloud/latest/veva3/getDeviceConfig',
  qs: {deviceId: 'abc123'},
  headers: {'x-api-key': '<YOUR_API_KEY>'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import http.client

conn = http.client.HTTPSConnection("api.inzwa.cloud")

payload = ""

headers = { 'x-api-key': "<YOUR_API_KEY>" }

conn.request("GET", "/latest/veva3/getDeviceConfig?deviceId=abc123", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Example Response

See sample configuration, JSON format.

setDeviceConfig

POST /veva3/setDeviceConfig?deviceId={deviceId}

Unlike the sendCommand method, the setDeviceConfig method allows for more than one configuration property to be changed at once. You're not required to submit all properties returned by the getDeviceConfig API method, just the ones you'd like to change. The API will respond with

{
  'status': 'Success'
}
on success or an error message.

On success, a configuration file with a .new suffix is written to the FTP server in the CONFIG directory. If the CHECK_CFG flag is set to true, the device will automatically download the configuration file the next time it uploads a scheduled PPV histogram file. Otherwise, command the device to download the new configuration file with the CFG DOWNLOAD command using the sendCommand API method. Allow a minute or two for the new configuration file to be written to the FTP server before issuing the CFG DOWNLOAD command.

Query Parameters

Parameter Required Description
{deviceId} Y Serial number of Veva III.

Payload

To change configuration properties on the device, create a JSON payload following the examples below. Please refer to the sample configuration, JSON format for a full list of configurable properties and the command reference for property details.

Example Payloads

{
  "MAIN": {
    "SEND_ALERT": true
  }
}

{
  "MAIN": {
    "SEND_ALERT": true
  },
  "000000_VIBR": {
    "PPV_MAX_X": 10.1,
    "PPV_MAX_Y": 10.1,
    "PPV_MAX_Z": 10.1,
    "FLG_ALT_X": true,
    "FLG_ALT_Y": true,
    "FLG_ALT_Z": true
  }
}

{
  "000000_VIBR": {
    "SAMP_FREQ": 1000,
    "ACC_SCALE": 8
  }
}

Example Requests

curl --request POST \
--url 'https://api.inzwa.cloud/latest/veva3/setDeviceConfig?deviceId=abc123' \
--header 'content-type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data '{
  "MAIN": {
    "SEND_ALERT": true
  }
}'

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api.inzwa.cloud/latest/veva3/setDeviceConfig',
  qs: {deviceId: 'abc123'},
  headers: {
    'x-api-key': '<YOUR_API_KEY>',
    'content-type': 'application/json'
  },
  body: {MAIN: {SEND_ALERT: true}},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import http.client

conn = http.client.HTTPSConnection("api.inzwa.cloud")

payload = "{\"MAIN\": {\"SEND_ALERT\": true}}"

headers = {
    'x-api-key': "<YOUR_API_KEY>",
    'content-type': "application/json"
    }

conn.request("POST", "/latest/veva3/setDeviceConfig?deviceId=abc123", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

getDevices

GET /veva3/getDevices

Returns a JSON array containing a list of device IDs accessible via this api and their types.

Example Requests

curl --request GET \
--url 'https://api.inzwa.cloud/latest/veva3/getDevices' \
--header 'x-api-key: <YOUR_API_KEY>'

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.inzwa.cloud/latest/veva3/getDevices',
  headers: {'x-api-key': '<YOUR_API_KEY>'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import http.client

conn = http.client.HTTPSConnection("api.inzwa.cloud")

payload = ""

headers = { 'x-api-key': "<YOUR_API_KEY>" }

conn.request("GET", "/latest/veva3/getDevices", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Example Response

[
  {
    'deviceSerialNum': 'abc123',
    'deviceType': 'Veva3'
  }
]

API Models

Command History Object

Field Type Description
id string The command's unique id.
command string Command sent to/from Veva III.
status string Status of the command. Sent indicates message set to device and delivered indicates message receipt was confirmed by the device. For messages coming from the device, the status will indicate received.
direction string Direction of the command. Either to_sim meaning to the Veva III's sim or from_sim.
dateCreated string Time command was created, in UTC.

Device Configuration Object

Please refer to the Sample Configuration Formats documentation for a complete example, in JSON format, of the device configuration object.

Object Description
MAIN Controls the main module settings. Details are available in the Main Commands documentation.
EXPORT Controls file export settings. Details are available in the Export Control Commands documentation.
REM_DIR_FLAT
REM_DIR_NEST		 Controls file path and naming conventions. Details are available in the File Path and Naming Conventions documentation.
SCHEDULE Controls scheduling of events on the device. Details are available in the Scheduling Commands documentation.
FTP Controls FTP server connection parameters. Details are available in the FTP Commands documentation.
SMS Controls M2M (SMS) notification numbers. Details are available in the M2M (SMS) Notification Commands documentation.
000000_VIBR Controls vibration sensor settings. Details are available in the Vibration Configuration Commands documentation.
Last update: March 8, 2024