TCP HELP

The Otii Server

The Otii server is an enterprise feature that allows the user to control the Otii application over a TCP socket using any language that supports TCP communication.

The communication with the server is performed using JSON messages sent to and from the server.

Message description

There is five types of messages request, response, progress, information and error.

Message types

Type Description
request Used for requests sent from the client.
response Server response on requests from client.
progress Server progress on requests supporting progress messaging
information Information messages sent from server not connected to a request.
error Error messages sent from server.

Request syntax

Key Type Required Description
type String Yes Type of message.
cmd String Yes Requested command.
trans_id String Optional Transaction id for matching response objects.
data Object Conditional Data for the command.
{
    "type": "request",
    "cmd": "arc_calibrate",
    "trans_id": "someId",
    "data": {
        "device_id": "Arc512031204843494E3130393033313036"
    }
}

Response syntax

Key Type Required Description
type String Yes Type of message.
cmd String Yes Requested command if the response is for a command request.
trans_id String Conditional Corresponding requests transaction id if provided in request.
data Object Conditional Data for response.
{
    "type": "response",
    "cmd": "otii_devices",
    "trans_id": "someId",
    "data": {
        "devices": [
            {
                "device_id": "Arc512031204843494E3130393033313036",
                "name": "fire",
                "type": "Arc"
            }
        ]
    }
}

Progress syntax

Key Type Required Description
type String Yes Type of message.
cmd String Yes Requested command.
progress_value Number Yes Progress described with a value from 0.0 to 1.0.
trans_id String Conditional Corresponding requests transaction id if provided in request.
data Object Conditional Progress data with more information if available.
{
    "type": "progress",
    "cmd": "otii_save_project",
    "progress_value": 0.73,
    "trans_id": "someId"
}

Information syntax

Key Type Required Description
type String Yes Type of message.
info String Yes Information message.
data Object Conditional Information data with more information.
{
    "type": "information",
    "info": "connected",
    "data": {
        "otii_version": "2.0.0",
        "protocol_version": "0.1",
        "server": "otii-server"
    }
}

Error syntax

Key Type Required Description
type String Yes Type of message.
errorcode String Yes The error code.
cmd String Conditional Requested command if the error is for a command request.
trans_id String Conditional Corresponding requests transaction id if provided in request.
data Object Conditional Error data with more information.
{
    "type": "error",
    "errorcode": "Device not connected",
    "cmd": "arc_set_main_voltage",
    "trans_id": "someId",
    "data": {
        "device_id": "Arc512031204843494E3130393033313036"
    }
}

Error messages

Description of error codes and data in error messages.

Data

Key Type Required Description
message String No More information about the failure.
id String No Device id if a failure is related to a specific device.
value All No Value if a failure is related to a specific key value.

Error codes

errorcode Description
Invalid command The requested command is not valid.
Not able to parse request Something went wrong when parsing the json request.
Missing key in request Required key is missing in the request.
Invalid key type Key with invalid type.
Invalid key value Key with invalid value.
Request too large Json request larger than allowed.
Command failure Failure when executing requested command.
Connection denied Connection was refused.
Command timeout Command execution timed out.
Device not connected Requested device not connected.
Command not valid for device type Command not valid for requested device type.

Not able to parse request data

Key Type Required Description
parse_error String Yes Error message when parsing JSON request
raw_data String Yes Received request that failed to be parsed

Missing key in request data

Key Type Required Description
key String Yes The missing key.

Invalid key type data

Key Type Required Description
key String Yes Request key with wrong JSON type.
expected_type String Yes Expected JSON type.
received_type String Yes Received JSON type.

Request too large data

Key Type Required Description
read_size Number Yes Bytes of received data when the request was aborted
max_size Number Yes Max allowed bytes in request

Otii requests

otii_create_project

Create a new project.

Request

Key Value
cmd "otii_create_project"

Response

Key Value
cmd "otii_create_project"
data otii_create_project data

Data

Key Type Required Description
project_id Number Yes The project id.
{
    "project_id": 1
}

otii_get_active_project

Returns the active project, if there is one.

Request

Key Value
cmd "otii_get_active_project"

Response

Key Value
cmd "otii_get_active_project"
data otii_get_active_project data

Data

Key Type Required Description
project_id Number Yes The project id if one exists, otherwise -1.
{
    "project_id": 1
}

otii_get_device_id

Get device id from device name.

Request

Key Value
cmd "otii_get_device_id"
data otii_get_device_id data

Data

Key Type Required Valid values
device_name String Yes Device name.
{
    "device_name": "Arc"
}

Response

Key Value
cmd "otii_get_device_id"
data otii_get_device_id data

Data

Key Type Required Description
device_id String Yes Device id of the first device with the requested name.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

otii_get_devices

List of connected devices.

Request

Key Value
cmd "otii_get_devices"

Response

Key Value
cmd "otii_get_devices"
data otii_get_devices data

Data

Key Type Required Description
devices Array Yes List of Device objects, empty array if no connected devices
{
    "devices": []
}

Device object

Key Type Required Description
device_id String Yes Unique id for the device
name String Yes Name of the device
type String Yes Type of device (Arc/UART)
{
    "device_id": "Arc12345678912345678912345678900001",
    "name": "Arc",
    "type": "Arc"
}

otii_open_project

Open an existing project.

If the filename passed to this function is relative, it will be relative to the server setting 'Project save destination' in Otii.

Request

Key Value
cmd "otii_open_project"
data otii_open_project data

Data

Key Type Required Valid values
filename String Yes File name for the project.
force Boolean No Set to true to open a file even if unsaved data exists. (false by default)
progress Boolean No To receive progress notifications when opening long recordings set this to true. (false by default)
{
    "filename": "myMeasurement.otii",
    "force": true,
    "progress": false
}

Response

Key Value
cmd "otii_open_project"
data otii_open_project data

Data

Key Type Required Description
project_id Number Yes The project id of the opened project.
filename String Yes Absolute path to opened project file.
{
    "project_id": 1,
    "filename": "/Users/qoitech/Documents/otii/myMeasurement.otii"
}

otii_set_all_main

Turn on or off the main power on all connected devices.

Request

Key Value
cmd "otii_set_all_main"
data otii_set_all_main data

Data

Key Type Required Valid values
enable Boolean Yes True turns on power, false turns off power.
{
    "enable": true
}

Response

Key Value
cmd "otii_set_all_main"

otii_shutdown

Shutdown TCP server.

Request

Key Value
cmd "otii_shutdown"
**Response**

Key | Value
--- | ---
**cmd** | "otii_shutdown"


## Project requests

### project_close

Close an open project.

**Request**

Key | Value
--- | ---
**cmd** | "project_close"
**data** | project_close data

**Data**

Key | Type | Required | Valid values
--- | --- | --- |---
**project_id** | Number | Yes | Project id
**force** | Boolean | No | If you want to close a project with unsaved data set this to true. (false by default)

```JSON
{
    "project_id": 1,
    "force": false
}

Response

Key Value
cmd "project_close"

project_crop_data

Crop all data.

Request

Key Value
cmd "project_crop_data"
data project_crop_data data

Data

Key Type Required Valid values
project_id Number Yes Project id
start Number Yes From sample time in seconds.
end Number Yes To sample time in seconds.
{
    "project_id": 1,
    "start": 2.5,
    "end": 10.50,
}

Response

Key Value
cmd "project_crop_data"

project_get_last_recording

Return last captured recording.

Request

Key Value
cmd "project_get_last_recordong"
data project_get_last_recording data

Data

Key Type Required Valid values
project_id Number Yes Project id
{
    "project_id": 1,
}

Response

Key Value
cmd "project_get_last_recording"
data project_get_last_recording data

Data

Key Type Required Description
recording_id Number Yes Recording id of last recording, or -1 if no recordings exists.
name String No Name of the recording
running Boolean No True for ongoing recordings
{
    "recording_id": 0,
    "name": "06/04 10:11:03",
    "running": false
}

project_get_recordings

Return list of captured recordings.

Request

Key Value
cmd "project_get_recordings"
data project_get_recordings data

Data

Key Type Required Valid values
project_id Number Yes Project id
{
    "project_id": 1,
}

Response

Key Value
cmd "project_get_recordings"
data project_get_recordings data

Data

Key Type Required Description
recordings Array Yes List of Recording objects, empty array if there is no recordings.
{
    "recordings": []
}

Recording object

Key Type Required Description
recording_id Number Yes Recording id
name String Yes Name of the recording
running Boolean Yes True for ongoing recordings
{
    "recording_id": 1,
    "name": "06/04 10:11:03",
    "running": false
}

project_save

Save the currently open project.

If the filename passed to this function is relative, it will be relative to the server setting 'Project save destination' in Otii.

Request

Key Value
cmd "project_save"
data project_save data

Data

Key Type Required Valid values
project_id Number Yes Project id
filename String Yes File name for the project.
force Boolean No Set to true to overwrite existing file. (false by default)
progress Boolean No To receive progress notifications when saving long recordings set this to true. (false by default)
{
    "project_id": 1,
    "filename": "myMeasurement.otii",
    "force": false,
    "progress": true
}

Response

Key Value
cmd "project_save"
data project_save data

Data

Key Type Required Description
filename String Yes Absolute path to saved project file .
{
    "filename": "myMeasurement.otii",
}

Progress

Key Value
cmd "project_save"
progress_value Progress of saving described with a value from 0.0 to 1.0.

project_start_recording

Start a new recording.

Request

Key Value
cmd "project_start_recording"
data project_start_recording data

Data

Key Type Required Valid values
project_id Number Yes Project id
{
    "project_id": 1,
}

Response

Key Value
cmd "project_start_recording"

project_stop_recording

Stop the running recording.

Request

Key Value
cmd "project_stop_recording"
data project_stop_recording data

Data

Key Type Required Valid values
project_id Number Yes Project id
{
    "project_id": 1,
}

Response

Key Value
cmd "project_stop_recording"

Recording requests

recording_delete

Delete a recording.

Request

Key Value
cmd "recording_delete"
data recording_delete data

Data

Key Type Required Valid values
recording_id Number Yes Recording id for the recording to delete

Response

Key Value
cmd "recording_delete"

recording_downsample_channel

Downsample all recordings on a channel.

Channels available for downsampling

Channel Description Unit
mc Main Current A
mv Main Voltage V
me Main Energy J
ac ADC Current A
av ADC Voltage V
ae ADC Energy J
sp Sense+ Voltage V
sn Sense- Voltage V
vb VBUS V
vj DC Jack V
tp Temperature °C

Request

Key Value
cmd "recording_downsample_channel"
data recording_downsample_channel data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
device_id String Yes Id of capturing device.
channel String Yes Channel name.
factor Number Yes Factor to downsample channel with.
{
    "recording_id": 1,
    "device_id": "Arc512031204843494E3130393033313036",
    "channel": "mc",
    "factor": 2
}

Response

Key Value
cmd "recording_downsample_channel"

See also:
arc_enable_channel

recording_get_channel_data_count

Get number of data entries in a channel for a specific recording.

Request

Key Value
cmd "recording_get_channel_data_count"
data recording_get_channel_data_count data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
device_id String Yes Id of capturing device.
channel String Yes Channel name.
{
    "recording_id": 0,
    "device_id": "Arc512031204843494E3130393033313036",
    "channel": "mc"
}

Response

Key Value
cmd "recording_get_channel_data_count"
data recording_get_channel_data_count data

Data

Key Type Required Description
count Number Yes Number of data entries in channel.
{
    "count": 332
}

See also:
arc_enable_channel

recording_get_channel_data_index

Get the index in a channel for a specific recording for the given timestamp.

Request

Key Value
cmd "recording_get_channel_data_index"
data recording_get_channel_data_index data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
device_id String Yes Id of capturing device.
channel String Yes Channel name.
timestamp Number Yes Timestamp in s.
{
    "recording_id": 0,
    "device_id": "Arc512031204843494E3130393033313036",
    "channel": "mc",
    "timestamp": 0.00250
}

Response

Key Value
cmd "recording_get_channel_data_index"
data recording_get_channel_data_index data

Data

Key Type Required Description
index Number Yes The index for the specified timestamp.
{
    "index": 332
}

See also:
arc_enable_channel

recording_get_channel_data

Get data entries from a specified channel of a specific recording.

Request

Key Value
cmd "recording_get_channel_data"
data recording_get_channel_data data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
device_id String Yes Device id of the capturing device.
channel String Yes The channel name.
index Number Yes Start index to fetch data entries from, first index at 0.
count Number Yes Number of data entries to fetch.
{
    "recording_id": 0,
    "device_id": "Arc512031204843494E3130393033313036",
    "channel": "mc",
    "index": 3,
    "count": 23
}

Response

Key Value
cmd "recording_get_channel_data"
data recording_get_channel_data data

Data for analog values

Key Type Required Description
data_type String Yes Set to "analog".
timestamp Number Yes Timestamp in seconds of first sample.
interval Number Yes Interval in seconds between each sample.
values Array Yes Array of samples.
{
    "data_type": "analog",
    "timestamp": 3.250,
    "interval": 0.00025,
    "values": [0.002453, 0.002675, 0.001945, 0.002444]
}

Data for gpi channels

Key Type Required Description
data_type String Yes Set to "digital".
values Array Yes Array with value objects.

Value object

Key Type Required Description
timestamp Number Yes Timestamp in seconds.
value Boolean Yes Digital value.

Gpi channel example

{
    "data_type": "digital",
    "values": [{
        "timestamp": 0.001,
        "value": true
    }, {
        "timestamp": 2.132,
        "value": false
    }]
}

Data for the rx channel

Key Type Required Description
data_type String Yes Set to "log".
values Array Yes Array with value objects.

Value object

Key Type Required Description
timestamp Number Yes Timestamp in seconds.
value String Yes Log text.
{
    "data_type": "log",
    "values": [{
        "timestamp": 0.001,
        "value": "Device booting"
    }, {
        "timsestamp": 2.132,
        "value": "Going to sleep"
    }]
}

See also:
otii_get_channel_data_count
arc_enable_channel

recording_get_log_offset

Returns the offset of a log.

Request

Key Value
cmd "recording_get_log_offset"
data recording_get_log_offset data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
device_id String No Device id of the capturing device. Exclude for imported logs.
channel String Yes The channel name. For imported logs, use the log_id returned by import_log.
{
    "recording_id": 0,
    "device_id": "Arc512031204843494E3130393033313036",
    "channel": "rx"
}

Response

Key Value
cmd "recording_get_log_offset"
data recording_get_log_offset data

Data

Key Type Required Description
offset Number Yes The current offset of the log.
{
    "offset": 1254
}

recording_get_offset

Returns the offset of the recording.

Request

Key Value
cmd "recording_get_offset"
data recording_get_offset data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
{
    "recording_id": 0
}

Response

Key Value
cmd "recording_get_offset"
data recording_get_offset data

Data

Key Type Required Description
offset Number Yes The current offset of the log.
{
    "offset": 1254
}

recording_import_log

Import a log file.

Request

Key Value
cmd "recording_import_log"
data recording_import_log data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
filename String Yes The path of the log to import.
converter String Yes The filename of the log converter to use (e.g. adb.lua).
{
    "recording_id": 0,
    "filename": "/home/jsmith/logs/log.txt",
    "converter": "adb.lua"
}

Response

Key Value
cmd "recording_import_log"
data recording_import_log data

Data

Key Type Required Description
log_id String Yes Id of imported log.
{
    "log_id": "file01.txt"
}

recording_is_running

Returns true if this recording is currently running.

Request

Key Value
cmd "recording_is_running"
data recording_is_running data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
{
    "recording_id": 0,
}

Response

Key Value
cmd "recording_is_running"
data recording_is_running data

Data

Key Type Required Description
running Boolean Yes True if the recording is currently running.
{
    "running": true
}

recording_log

Write text to time synchronized log window.

This function will add a timestamped text to a log. The first time it is called, it will create a new log. Note that a recording has to be running for this to produce any output.

Request

Key Value
cmd "recording_log"
data recording_log data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
text String Yes Text to add to the log window.
timestamp Int No Timestamp in milliseconds since 1970-01-01. If omitted the current time will be used.
{
    "recording_id": 0,
    "text": "Bluetooth turned on",
    "timestamp": 1567162782961
}

Response

Key Value
cmd "recording_log"

recording_rename

Rename recording.

Request

Key Value
cmd "recording_rename"
data recording_rename data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
name String Yes New name of recording.
{
    "recording_id": 0,
    "name": "First recording"
}

Response

Key Value
cmd "recording_rename"

recording_set_log_offset

Set offset of a log.

Request

Key Value
cmd "recording_set_log_offset"
data recording_set_log_offset data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
device_id String No Device id of the capturing device. Exclude for imported logs.
channel String Yes The channel name. For imported logs, use the log_id returned by import_log.
offset Number Yes The new offset to apply in microseconds.
{
    "recording_id": 0,
    "device_id": "Arc512031204843494E3130393033313036",
    "channel": "rx",
    "offset": 1254
}

Response

Key Value
cmd "recording_set_log_offset"

recording_set_offset

Sets the offset of the recording.

Request

Key Value
cmd "recording_set_offset"
data recording_set_offset data

Data

Key Type Required Valid values
recording_id Number Yes Recording id.
offset Number Yes The new offset to apply in microseconds.
{
    "recording_id": 0,
    "offset": 1254
}

Response

Key Value
cmd "recording_set_offset"

Arc specific requests

arc_calibrate

Perform internal calibration of an Arc device.

Request

Key Value
cmd "arc_calibrate"
data arc_calibrate data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd arc_calibrate

arc_enable_5v

Enable 5V in expansion port.

Request

Key Value
cmd "arc_enable_5v"
data arc_enable_5v data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
enable Boolean Yes True enables 5V output, false disables it.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "enable": true
}

Response

Key Value
cmd arc_enable_5v

arc_enable_battery_profiling

Note: This request requires a battery toolbox license.

This will start the discharge profiling of a connected battery.

Request

Key Value
cmd "arc_enable_battery_profiling"
data arc_enable_battery_profiling data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
enable Boolean Yes True to start battery profiling, false to stop.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "enable": true
}

Response

Parameter Value
cmd "arc_enable_battery_profiling"

arc_enable_channel

Enable or disable measurement channel.

Available channels

Channel Description Unit
mc Main Current A
mv Main Voltage V
ac ADC Current A
av ADC Voltage V
sp Sense+ Voltage V
sn Sense- Voltage V
vb VBUS V
vj DC Jack V
tp Temperature °C
rx UART logs text
i1 GPI1 Digital
i2 GPI2 Digital

In addition to above channels, two more channels are enabled automatically when their respective current channel is enabled:

Channel Description Unit
me Main Energy J
ae ADC Energy J

Request

Key Value
cmd "arc_enable_channel"
data arc_enable_channel data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
channel String Yes Channel.
enable Boolean Yes True to enable and false to disable channel.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "channel": "mc",
    "enable": true
}

Response

Key Value
cmd "arc_enable_channel"

arc_enable_exp_port

Enables the expansion port.

Required to be enabled to use digital pins (GPO, GPI, RX and TX).

Request

Key Value
cmd "arc_enable_exp_port"
data arc_enable_exp_port data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
enable Boolean Yes True to enable and false to disable exp port.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "enable": true
}

Response

Key Value
cmd "arc_enable_exp_port"

arc_enable_uart

Enables RX and TX pins to be a UART.

Required to be disabled to use RX and TX pins as GPI/GPO.

Request

Key Value
cmd "arc_enable_uart"
data arc_enable_uart data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
enable Boolean Yes True to enable and false to disable UART.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "enable": true
}

Response

Key Value
cmd "arc_enable_uart"

arc_get_4wire

Get the 4-wire measurement state.

Request

Key Value
cmd "arc_get_4wire"
data arc_get_4wire data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_4wire"
data arc_get_4wire data

Data

Key Type Required Description
value String Yes The current state, "cal_invalid", "disabled", "inactive" or "active".
{
    "value": true
}

See also:
arc_set_4wire

arc_get_adc_resistor

Get adc resistor value.

Request

Key Value
cmd "arc_get_adc_resistor"
data arc_get_adc_resistor data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_adc_resistor"
data arc_get_adc_resistor data

Data

Key Type Required Description
value Number Yes Resistance in Ω.
{
    "value": 4.7
}

arc_get_exp_voltage

Get the voltage of the expansion port.

Request

Key Value
cmd "arc_get_exp_voltage"
data arc_get_exp_voltage data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_exp_voltage"
data arc_get_exp_voltage data

Data

Key Type Required Description
value Number Yes Expansion port voltage in V.
{
    "value": 3.4
}

arc_get_gpi

Get the state of a GPI pin.

Requires expansion port to be enabled.

Request

Key Value
cmd "arc_get_gpi"
data arc_get_gpi data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
pin Number Yes Id of the GPI pin, 1 or 2.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "pin": 1
}

Response

Key Value
cmd "arc_get_gpi"
data arc_get_gpi data

Data

Key Type Required Description
value Boolean Yes The state of the GPI pin.
{
    "value": true
}

See also:
arc_enable_exp_port

arc_get_main_voltage

Get main voltage value.

Request

Key Value
cmd "arc_get_main_voltage"
data arc_get_main_voltage data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_main_voltage"
data arc_get_main_voltage data

Data

Key Type Required Description
value Number Yes Voltage in V.
{
    "value": 3.4
}

arc_get_max_current

Get the max allowed current.

Request

Key Value
cmd "arc_get_max_current"
data arc_get_max_current data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_max_current"
data arc_get_max_current data

Data

Key Type Required Description
value Number Yes The max current in A.
{
    "value": 0.564
}

arc_get_range

Get the current measurement range on the main output.

Request

Key Value
cmd "arc_get_range"
data arc_get_range data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_range"
data arc_get_range data

Data

Key Type Required Description
range String Yes The current range, "low" or "high"
{
    "range": "high"
}

arc_get_rx

The RX pin can be used as a GPI when the UART is disabled.

Requires expansion port to be enabled.

Request

Key Value
cmd "arc_get_rx"
data arc_get_rx data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_rx"
data arc_get_rx data

Data

Key Type Required Description
value Bool Yes The state of the RX pin.
{
    "value": true
}

See also:
arc_enable_exp_port
arc_enable_uart

arc_get_src_cur_limit_enabled

Get current state of voltage source current limiting.

Request

Key Value
cmd "arc_get_src_cur_limit_enabled"
data arc_get_src_cur_limit_enabled data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_src_cur_limit_enabled"
data arc_get_src_cur_limit_enabled data

Data

Key Type Required Description
enabled Boolean Yes True if set to constant current, false if set to cut-off.
{
    "enabled": true
}

See also:
arc_set_src_cur_limit_enabled

arc_get_supplies

Note: This request requires a battery toolbox license.

Get a list of all available supplies for the device. Supply id 0 always refers to the power box.

Request

Key Value
cmd "arc_get_supplies"
data arc_get_supplies data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_supplies"
data arc_get_supplies data

Data

Key Type Required Description
supplies Array Yes List of all available supplies.
{
    "supplies": [{
        "supply_id": 1,
        "name": "Power box"
    }, {
        "supply_id": 2,
        "name": "CR2032-NoName",
        "manufacturer": "NoName",
        "model": "CR2032"
    }]
}

Supply object

Key Type Required Description
supply_id Number Yes Supply id
name String Yes Name
manufacturer String No Battery manufacturer.
model String No Battery model.

arc_get_supply

Note: This request requires a battery toolbox license.

Get current power supply id.

Request

Key Value
cmd "arc_get_supply"
data arc_get_supply data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_supply"
data arc_get_supply data

Data

Key Type Required Description
supply_id Number Yes The current supply id.
{
    "supply_id": 2
}

See also:
arc_get_supplies

arc_get_supply_parallel

Note: This request requires a battery toolbox license.

Get current number of simulated batteries in parallel.

Request

Key Value
cmd "arc_get_supply_parallel"
data arc_get_supply_parallel data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_supply_parallel"
data arc_get_supply_parallel data

Data

Key Type Required Description
value Number Yes The number of batteries in parallel.
{
    "value": 2
}

See also:
arc_get_supplies

arc_get_supply_series

Note: This request requires a battery toolbox license.

Get current number of simulated batteries in series.

Request

Key Value
cmd "arc_get_supply_series"
data arc_get_supply_series data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_supply_series"
data arc_get_supply_series data

Data

Key Type Required Description
value Number Yes The number of batteries in series.
{
    "value": 2
}

See also:
arc_get_supplies

arc_get_supply_soc_tracking

Note: This request requires a battery toolbox license.

Get current state of power supply State of Charge tracking.

Request

Key Value
cmd "arc_get_supply_soc_tracking"
data arc_get_supply_soc_tracking data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_supply_soc_tracking"
data arc_get_supply_soc_tracking data

Data

Key Type Required Description
enabled Boolean Yes True if State of Charge tracking is enabled, otherwise false.
{
    "enabled": true
}

See also:
arc_get_supplies

arc_get_supply_used_capacity

Note: This request requires a battery toolbox license.

Get current power supply used capacity.

Request

Key Value
cmd "arc_get_supply_used_capacity"
data arc_get_supply_used_capacity data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_supply_used_capacity"
data arc_get_supply_used_capacity data

Data

Key Type Required Description
value Number Yes Capacity in coulombs (divide by 3.6 to get mAh)
{
    "value": 50.0
}

See also:
arc_get_supplies

arc_get_uart_baudrate

Get the UART baud rate.

Request

Key Value
cmd "arc_get_uart_baudrate"
data arc_get_uart_baudrate data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_uart_baudrate"
data arc_get_uart_baudrate data

Data

Key Type Required Description
value Number Yes The requested baud rate.
{
    "value": 115200
}

arc_get_value

Get value from specified channel.

Command not available for the rx channel.

Request

Key Value
cmd "arc_get_value"
data arc_get_value data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
channel String Yes The channel name.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "channel": "mc"
}

Response

Key Value
cmd "arc_get_value"
data arc_get_value data

Data

Key Type Required Description
value Number Yes The value in A, V, °C and Digital.
{
    "value": 0.0375
}

See also:
arc_enable_channel

arc_get_version

Get hardware and firmware versions of device.

Request

Key Value
cmd "arc_get_version"
data arc_get_version data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_get_version"
data arc_get_version data

Data

Key Type Required Description
hw_version String Yes The hardware version.
fw_version String Yes The firmware version.
{
    "hw_version": "1.2",
    "fw_version": "1.0.8"
}

arc_is_connected

Check if a device is connected

Request

Key Value
cmd "arc_is_connected"
data arc_is_connected data

Data

Key Type Required Valid values
device_id String Device id
{
    "device_id": "Arc512031204843494E3130393033313036"
}

Response

Key Value
cmd "arc_is_connected"
data arc_is_connected data

Data

Key Type Required Description
connected Boolean Yes True if device is connected
{
    "connected": true
}

arc_set_4wire

Enable/disable 4-wire measurements using Sense+/-.

Request

Key Value
cmd "arc_set_4wire"
data arc_set_4wire data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
enable Boolean Yes True to enable 4-wire, false to disable
{
    "device_id": "Arc512031204843494E3130393033313036",
    "enable": true
}

Response

Parameter Value
cmd "arc_set_4wire"

See also:
arc_get_4wire

arc_set_adc_resistor

Set the value of the shunt resistor for the ADC.

Request

Key Value
cmd "arc_set_adc_resistor"
data arc_set_adc_resistor data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
value Number Yes The ADC resistor in Ω (0.001 to 22Ω).
{
    "device_id": "Arc512031204843494E3130393033313036",
    "value": 4.7
}

Response

Parameter Value
cmd "arc_set_adc_resistor"

arc_set_battery_profile

Note: This request requires a battery toolbox license.

Set the battery profile.

Request

Key Value
cmd "arc_set_battery_profile"
data arc_set_battery_profile data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
value Array Yes The list of battery profile step objects (max 10). Each object is of the { "current
{
    "device_id": "Arc512031204843494E3130393033313036",
    "value": [{
        "current": 0.001,
        "duration": 0.01
    }, {
        "power": 2,
        "duration": 3.5
    }]
}

Response

Parameter Value
cmd "arc_set_battery_profile"

arc_set_exp_voltage

Set the voltage of the expansion port.

Request

Key Value
cmd "arc_set_exp_voltage"
data arc_set_exp_voltage data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
value Number Yes Voltage in V (1.2 - 5V).
{
    "device_id": "Arc512031204843494E3130393033313036",
    "value": 2.7
}

Response

Parameter Value
cmd "arc_set_exp_voltage"

arc_set_gpo

Set the state of a GPO.

Requires expansion port to be enabled.

Request

Key Value
cmd "arc_set_gpo"
data arc_set_gpo data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
pin Number Yes Id of the GPI pin, 1 or 2.
value Boolean Yes State of pin
{
    "device_id": "Arc512031204843494E3130393033313036",
    "pin": 1,
    "value": true
}

Response

Parameter Value
cmd "arc_set_gpo"

See also:
arc_enable_exp_port

arc_set_main

Turn on or off main power on a device.

Request

Key Value
cmd "arc_set_main"
data arc_set_main data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected device.
enable Boolean Yes True turns on power, false turns off power.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "enable": true
}

Response

Key Value
cmd "arc_set_main"

arc_set_main_current

Set the main current on Arc.

Used when the Otii device is set in constant current mode.

Request

Key Value
cmd "arc_set_main_current"
data arc_set_main_current data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
value Number Yes Current to set in A.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "value": 0.005
}

Response

Parameter Value
cmd "arc_set_main_current"

arc_set_main_voltage

Set the main voltage on Arc.

Used when the Otii device is set in constant voltage mode.

Request

Key Value
cmd "arc_set_main_voltage"
data arc_set_main_voltage data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
value Number Yes Voltage to set in V.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "value": 2.3
}

Response

Parameter Value
cmd "arc_set_main_voltage"

arc_set_max_current

When the current exceeds this value, the main power will cut off.

Request

Key Value
cmd "arc_set_max_current"
data arc_set_max_current data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
value Number Yes Max current in A.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "value": 0.6
}

Response

Parameter Value
cmd "arc_set_max_current"

arc_set_power_regulation

Set power regulation mode.

Request

Key Value
cmd "arc_set_power_regulation"
data arc_set_power_regulation data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
mode String Yes One of the following: "voltage", "current", "off".
{
    "device_id": "Arc512031204843494E3130393033313036",
    "mode": "current"
}

Response

Parameter Value
cmd "arc_set_power_regulation"

arc_set_range

Set the main outputs measurement range.

Request

Key Value
cmd "arc_set_range"
data arc_set_range data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
range String Yes "low" or "high". "low" will enable auto-range, "high" will force the use of high-range.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "range": "low"
}

Response

Parameter Value
cmd "arc_set_range"

arc_set_src_cur_limit_enabled

Enable voltage source current limit (CC) operation.

Request

Key Value
cmd "arc_set_src_cur_limit_enabled"
data arc_set_src_cur_limit_enabled data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
enable Boolean Yes True means enable constant current, false means cut-off.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "enable": true
}

Response

Parameter Value
cmd "arc_set_src_cur_limit_enabled"

arc_set_supply

Note: This request requires a battery toolbox license.

Set power supply type.

Request

Key Value
cmd "arc_set_supply"
data arc_set_supply data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
supply_id Number Yes Supply id, as returned by get_supplies.
series Number No Number of batteries in series, defaults to 1.
parallel Number No Number of batteries in parallel, defaults to 1.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "supply_id": 2,
    "series": 1,
    "parallel": 2
}

Response

Parameter Value
cmd "arc_set_supply"

See also:
arc_get_supplies

arc_set_supply_soc_tracking

Note: This request requires a battery toolbox license.

Set power supply State of Charge tracking.

Request

Key Value
cmd "arc_set_supply_soc_tracking"
data arc_set_supply_soc_tracking data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
enable Boolean Yes True enables State of Charge tracking, false disables it.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "enable": true
}

Response

Parameter Value
cmd "arc_set_supply_soc_tracking"

arc_set_supply_used_capacity

Note: This request requires a battery toolbox license.

Set power supply used capacity.

Request

Key Value
cmd "arc_set_supply_used_capacity"
data arc_set_supply_used_capacity data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
value Number Yes Capacity in coulombs (multiply mAh by 3.6 to get C)
{
    "device_id": "Arc512031204843494E3130393033313036",
    "value": 50.0
}

Response

Parameter Value
cmd "arc_set_supply_used_capacity"

arc_set_tx

The TX pin can be used as a GPO when the UART is disabled.

Requires expansion port to be enabled.

Request

Key Value
cmd "arc_set_tx"
data arc_set_tx data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
value Boolean Yes State of tx pin
{
    "device_id": "Arc512031204843494E3130393033313036",
    "value": true
}

Response

Parameter Value
cmd "arc_set_tx"

See also:
arc_enable_exp_port
arc_enable_uart

arc_set_uart_baudrate

Set UART baud rate.

Request

Key Value
cmd "arc_set_uart_baudrate"
data arc_set_uart_baudrate data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
value Number Yes Baud rate to set.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "value": 115200
}

Response

Parameter Value
cmd "arc_set_uart_baudrate"

arc_wait_for_battery_data

Note: This request requires a battery toolbox license.

Wait for battery data.

Request

Key Value
cmd "arc_wait_for_battery_data"
data arc_wait_for_battery_data data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected Arc device.
timeout Number Yes Maximum timeout in ms. May time out earlier if another Arc is returning battery data.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "timeout": 100
}

Response

Key Value
cmd "arc_wait_for_battery_data"
data arc_wait_for_battery_data data

Data

Key Type Required Description
value Object Yes Battery data object or empty if timeout. The object will contain "timestamp" in seconds,
"iteration", "step", "voltage" at the end of the current step and "discharge" in coulombs accumulating
the total discharge of the battery since profiling start.
{
    "value": { "timestamp" : 0.1, "iteration" : 10000, "step" : 0, "voltage" : 3.654, "discharge" : 1.234 }
}

See also:
arc_enable_battery_profiling

arc_write_tx

Write data to TX.

Requires expansion port and UART to be enabled.

Request

Key Value
cmd "arc_write_tx"
data arc_write_tx data

Data

Key Type Required Valid values
device_id String Yes Device id for a connected arc.
value String Yes Data to write.
{
    "device_id": "Arc512031204843494E3130393033313036",
    "value": "Start"
}

Response

Parameter Value
cmd "arc_write_tx"

See also:
arc_enable_exp_port
arc_enable_uart