otii_tcp_client

Otii TCP Client

Install the Otii TCP Client for Python:

python3 -m pip install otii-tcp-client

arc

class otii_tcp_client.arc.Arc(device_dict, connection)

Class to define an Arc or Ace device.: Includes operations that can be run on the Arc or Ace.

type

Device type, “Arc” for Arc devices.

Type:: str

id

ID of the Arc device.

Type:: str

name

Name of the Arc device.

Type:: str

connection

Object to handle connection to the Otii server.

Type:: OtiiConnection

__init__(device_dict, connection)

Parameters:

device_dict (dict) – Dictionary with Arc parameters.
connection (OtiiConnection) – Object to handle connection to the Otii server.

add_to_project() → None: Add device to current project.

calibrate() → None: Perform internal calibration of an Arc device.

enable_5v(enable: bool) → None

Enable or disable 5V pin.

Parameters:: enable (bool) – True to enable 5V, False to disable.

enable_channel(channel: str, enable: bool) → None

Enable or disable measurement channel.

Available channels
Channel	Description	Unit
mc	Main Current	A
mp	Main Power	W
mv	Main Voltage	V
ac	ADC Current	A
ac	ADC Power	W
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

Parameters:

channel (str) – Name of the channel to enable or disable.
enable (bool) – True to enable channel, False to disable.

enable_exp_port(enable: bool) → None

Enable expansion port.

Parameters:: enable (bool) – True to enable expansion port, False to disable.

enable_uart(enable: bool) → None

Enable UART.

Parameters:: enable (bool) – True to enable UART, False to disable.

firmware_upgrade(filename: str | None = None) → None

Initiate device firmware update.

Parameters:: filename (str, optional) – Firmware filename.

get_4wire() → str

Get the 4-wire measurement state.

Returns:: The current state, “cal_invalid”, “disabled”, “inactive” or “active”.
Return type:: str

get_adc_resistor() → float

Get adc resistor value.

Returns:: ADC resistor value (Ohm).
Return type:: float

get_channel_samplerate(channel: str) → int

Get channel sample rate.

For available channels see Arc.enable_channel()

Parameters:: channel (str) – Name of the channel to get the sample rate for.
Returns:: Sample rate for channel
Return type:: int

get_exp_voltage() → float

Get the voltage of the expansion port.

Returns:: Voltage value on the expansion port (V).
Return type:: float

get_gpi(pin: int) → bool

Get the state of one of the GPI pins.

Parameters:: pin (int) – ID of the GPI pin to get state of, 1 or 2.
Returns:: State of the GPI pin.
Return type:: bool

get_main() → bool

Get the state of the main power.

Returns:: State of the main power.
Return type:: bool

get_main_voltage() → float

Get main voltage value.

Returns:: Main voltage value (V).
Return type:: float

get_max_current() → float

Get the max allowed current.

Returns:: Value max current is set to (A).
Return type:: float

get_range() → str

Get the current measurement range on the main output.

Returns:: Current measurement range mode on main, “low” or “high”.
Return type:: str

get_rx() → bool

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

Returns:: State of the RX pin.
Return type:: bool

get_src_cur_limit_enabled() → bool

Get current state of voltage source current limiting.

Returns:: True if set to constant current, false if set to cut-off.
Return type:: bool

get_supply_mode() → str

Get current supply mode

Returns:: “power-box” or “battery-emulator”
Return type:: string

get_uart_baudrate() → int

Get the UART baud rate.

Returns:: Value UART baud rate is set to.
Return type:: int

get_value(channel: str) → float

Get value from specified channel.

This is not available for the rx channel.

For available channels see Arc.enable_channel()

Parameters:: channel (str) – Name of the channel to get value from.
Returns:: Present value in the channel (A/V/°C/Digital).
Return type:: float

get_version() → dict

Get hardware and firmware versions of device.

Returns:: Dictionary including keys hw_version (str) and fw_version (str).
Return type:: dict

is_connected() → bool

Check if a device is connected.

Returns:: True if device is connected, False otherwise.
Return type:: bool

set_4wire(enable: bool) → None

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

Parameters:: enable (bool) – True to enable 4-wire, false to disable

set_adc_resistor(value: float) → None

Set the value of the shunt resistor for the ADC.

Parameters:: value (float) – Value to set ADC resistor to, value should be between 0.001-22 (Ohm).

set_channel_samplerate(channel: str, value: int) → None

Set the sample rate of a channel

For available channels see Arc.enable_channel()

Parameters:

channel (str) – Name of the channel to set the sample rate for.
value (int) – The sample rate to set

set_exp_voltage(value: float) → None

Set the voltage of the expansion port.

Parameters:: value (float) – Value to set expansion port voltage to, value should be between 1.2-5 (V).

set_gpo(pin: int, value: bool) → None

Set the state of one of the GPO pins.

Parameters:

pin (int) – ID of the GPO pin to set state of, 1 or 2.
value (bool) – True to enable GPO output, False to disable.

set_main(enable: bool) → None

Turn on or off main power on a device.

Parameters:: enable (bool) – True to turn on main power, False to turn off.

set_main_current(value: float) → None

Set the main current on Arc. Used when the Otii device is set in constant current mode.

Parameters:: value (float) – Current to set in (A).

set_main_voltage(value: float) → None

Set the main voltage on Arc.

Parameters:: value (float) – Value to set main voltage to (V).

set_max_current(value: float) → None

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

Parameters:: value (float) – Value to set max current to, value should be between 0.001-5 (A).

set_power_regulation(mode: Literal['voltage', 'current', 'inline', 'off']) → None

Set power regulation mode.

Parameters:: mode (str) – One of the following: “voltage”, “current”, “inline”, “off”.

set_range(arange: Literal['low', 'high']) → None

Set the main outputs measurement range.

Parameters:: range (str) – Current measurement range mode to set on main. “low” enables auto-range, “high” force high-range.

set_src_cur_limit_enabled(enable: bool) → None

Enable voltage source current limit (CC) operation.

Parameters:: enable (bool) – True means enable constant current, false means cut-off.

set_supply_battery_emulator(battery_profile_id: str, *, series: int = 1, parallel: int = 1, used_capacity: int | None = None, soc: int | None = None, soc_tracking: bool = True) → BatteryEmulator

Set power supply to battery emulator.

It is only possible to set one of used_capacity and soc. If neither is set, used_capacity is set to 0, and soc to 100.

Parameters:

battery_profile_id (string) – Id of battery profile, as returned by otii.get_battery_profiles.
series (int, optional) – Number of batteries in series, defaults to 1.
parallel (int, optional) – Number of batteries in parallel, defaults to 1.
used_capacity (int, optional) – Used capacity, defaults to 0.
soc (int, optional) – State of Charge, defaults to 100.
soc_tracking (bool, optional) – State of Charge tracking, defaults to True.

Returns:

BatteryEmulator

set_supply_power_box() → None: Set power supply to power box.

set_tx(value: bool) → None

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

Parameters:: value (bool) – True to enable TX output, False to disable.

set_uart_baudrate(value: int) → None

Set UART baud rate.

Parameters:: value (int) – Value to set UART baud rate to.

write_tx(value: str) → None

Write data to TX.

Parameters:: value (str) – Data to write to TX.

otii

class otii_tcp_client.otii.Otii(connection=None)

Class to define an Otii object.

connection

Object to handle connection to the Otii server.

Type:: OtiiConnection

__init__(connection=None)

Parameters:: connection (OtiiConnection) – Object to handle connection to the Otii server.

create_project() → Project

Create a new project.

Returns:: Project

get_active_project() → Project

Returns the active project if there is one.

Returns:: Project

get_battery_profile_info(battery_profile_id: str) → dict

Returns informatiion about a battery profile.

Parameters:

battery_profile_id (string) – Battery profile id.

Returns:

Battery profile info

```{code-block} python3 {

”battery_profile_id”:”6ef4a003-22c6-44d1-9e37-21de0526f5f2” “name”:”AAA Super Charged”, “battery”: {

”capacity”:207.07, “capacityunit”:”mAh”, “cutoffvoltage”:3, “manufacturer”:”MikroE”, “maxtemperature”:60, “mintemperature”:-20, “model”:”190mAh_LiPo”, “size”:””, “sizeunit”:”mm”, “temperatureunit”:”°C”, “voltage”:3.6, “voltageunit”:”V”, “weight”:0, “weightunit”:”g”, “worktemperature”:20

} “discharge_tables”: [{

”dischargetable_id”:”22dbed46-1b83-4e04-8964-aa4e5187f3cc”

}]

Return type:

dict

get_battery_profiles() → list[dict]

Returns a list of available battery profiles.

Returns:

List of battery profile objects:

[{
    "battery_profile_id": "1ce61608-9164-41a9-affb-221f1ea9f187",
    "name": "CR2032-NoName",
    "manufacturer": "NoName",
    "model": "CR2032"
}, {
    "battery_profile_id": "b2ce2796-80f7-4386-8759-be31466927b8",
    "name": "CR2450-NoName",
    "manufacturer": "NoName",
    "model": "CR2450"
}]

Return type:

list

get_device_id(device_name: str) → str

Get device id from device name.

Parameters:: device_name (str) – Name of device to get ID of.
Returns:: Device ID of requested device.
Return type:: str

get_devices(timeout: int = 10, devicefilter: tuple[str] | None = None) → list[Arc]

Get a list of connected devices.

Parameters:

timeout (int, optional) – Timeout in seconds to wait for avaliable devices.
devicefilter (tuple, optional) – Override default device filter

Returns:

List of Arc device objects:

[{
    "device_id": "Arc12345678912345678912345678900001",
    "name": "Arc I",
    "type": "Arc"
}, {
    "device_id": "Arc12345678912345678912345678900005",
    "name": "Arc II",
    "type": "Arc"
}]

get_licenses() → list[dict]

Return a list of all licenses for logged in user

Returns:

List of licenses:

[{
    "id":1234,
    "type":"Automation",
    "available":true,
    "reserved_to":"",
    "hostname":""
}, {
    "id":5432,
    "type":"Battery",
    "available":true,
    "reserved_to":"joe",
    "hostname":"computer_one"
}]

has_license(license_type: str) → bool

Check if user has a reserved license

Parameters:: license_type (str) – Type of license
Returns:: True if license is reserved, otherwise False
Return type:: bool

is_logged_in() → bool

Check if user is logged in

Returns:: True if user is logged in, otherwise False
Return type:: bool

login(username: str, password: str) → None

Login user

Parameters:

username (str) – Name of Otii user
password (str) – Password of Otii user

logout() → None: Logout user

open_project(filename: str, force=False, progress=False) → Project

Open an existing project.

Parameters:

filename (str) – Name of project file.
force (bool, optional) – True to open even if unsaved data exists, False not to.
progress (bool, optional) – True to receive notifications about progress of opening file,
to. (False not)

Returns:

Project

reserve_license(license_id: int) → None

Reserve license

Parameters:: license_id (int) – The license id to reserve.

return_license(license_id: int) → None

Return license

Parameters:: license_id (int) – The license id to return.

set_all_main(enable: bool) → None

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

Parameters:: enable (bool) – True to turn on main power, False to turn off.

shutdown() → None: Shutdown Otii

exception otii_tcp_client.otii.OtiiException

otii_client

class otii_tcp_client.otii_client.Connect(host: str, port: int, try_for_seconds: int, licensing: LicensingMode, credentials: str, licenses: list[str])

class otii_tcp_client.otii_client.LicensingMode(*values)

class otii_tcp_client.otii_client.OtiiClient

Use this class to easily create a connected Otii object.

connect(*, host='127.0.0.1', port=1905, try_for_seconds=10, licensing=LicensingMode.AUTO, credentials='./credentials.json', licenses=None) → Connect

Connect to Otii.

Setting the licensing parameter to AUTO:

If not logged in, tries to log in using provided credentials and will logout when disconnected

If not all licenses specified in licenses already are reserved, it will try to automatically reserve the needed licenses, and then return them when disconnected

Credentials will be read from the file credentials, or read from the environment variables OTII_USERNAME and OTII_PASSWORD.

Parameters:

host (str, optional) – Server address.
port (int, optional) – Connection port number.
try_for_seconds (int, optional) – Seconds to try to connect.
licensing (str, optional) – ‘auto’ or ‘manual’.
credentials (str, optional) – Path to a file containing credentials.
licenses (str[], optional) – Array of license types (‘Automation’, ‘Battery’) needed.

disconnect() → None: Disconnect from Otii.

exception otii_tcp_client.otii_client.OtiiClientException

otii_connection

exception otii_tcp_client.otii_connection.DisconnectedException

class otii_tcp_client.otii_connection.OtiiConnection(address: str, port: int)

Class to define the server connection handler

host_address

Server IP address.

Type:: str

host_port

Connection port number.

Type:: int

recv_buffer

Size of receive buffer.

Type:: int

sock

Communication socket.

Type:: socket

__init__(address: str, port: int)

Parameters:

address (str) – Server IP address.
port (int) – Connection port number.

close_connection() → None: Close connection to server.

connect_to_server(*, try_for_seconds: int = 0) → dict

Connect to server.

Parameters:

try_for_seconds (int) – Seconds to try to connect.

Returns:

Server information:

{
    "type": "information",
    "info": "connected",
    "data": {
        "otii_version": "3.5.5",
        "protocol_version": "0.1",
        "server": "otii-server"
    }
}

receive_response(timeout_seconds: int | None, trans_id: str) → dict

Receive a JSON formated response from the server.

Parameters:

timeout_seconds (int) – Transmission timeout (s).
trans_id (str) – ID of transmission.

Returns:

Decoded JSON server response.

Return type:

dict

send(request: str) → None

Send request without waiting for response.

Parameters:: request (dict) – Server request.

send_and_receive(request: dict, timeout: int | None = 3) → dict

Send request and receive response from server.

Parameters:

request (dict) – Server request.
timeout (int, optional) – Transmission timeout (s), default 3s.

Returns:

Decoded JSON server response.

Return type:

dict

send_request(message: str)

Send request to server.

Parameters:: message (str) – Server request.

otii_exception

exception otii_tcp_client.otii_exception.Otii_Exception(response)

Class to define an Otii Exception object

type

Error code type.

Type:: str

message

Human readable error message.

Type:: str

__init__(response)

Parameters:: response (dict) – Dictionary with error message from server.

project

class otii_tcp_client.project.Project(id: int, connection: OtiiConnection)

Class to define an Otii Project object.

id

ID of project.

Type:: int

connection

Object to handle connection to the Otii server.

Type:: OtiiConnection

__init__(id: int, connection: OtiiConnection)

Parameters:

id (int) – ID of project.
filename (str) – Name of project. Set when project is opened or saved.
connection (OtiiConnection) – Object to handle connection to the Otii server.

close(force: bool = False) → None

Close the project.

Parameters:: force (bool, optional) – True to force close, e.g. ignore unsaved data warning, False to not override warnings.

crop_data(start: float, end: float) → None

Crop all data before start and after end.

Parameters:

start (float) – From sample at time start (s).
end (float) – To sample at time end (s).

get_last_recording() → Recording

Get the latest recording in the project.

Returns:: Recording

get_recordings() → list[Recording]

List captured recordings.

Returns:: list[Recording]

save(progress: bool = False) → str

Save the project.

Parameters:: progress (bool, optional) – True to receive notifications about save progress, False to not receive any notifications.
Returns:: Name of saved file.
Return type:: str

save_as(filename: str, force: bool = False, progress: bool = False) → str

Save the project as.

Parameters:

filename (str) – Name of project file.
force (bool, optional) – True to overwrite existing file, False to not overwrite.
progress (bool, optional) – True to receive notifications about save progress, False to not receive any notifications.

Returns:

Name of saved file.

Return type:

str

start_recording() → None: Start a new recording.

stop_recording() → None: Stop the running recording.

recording

class otii_tcp_client.recording.Recording(recording_dict: dict, connection: OtiiConnection)

Class to define an Otii Recording object.

id

ID of the recording.

Type:: int

name

Name of the recording.

Type:: string

start_time

Start of the recording or None if unsupported by TCP server.

Type:: datetime.datetime

connection

Object to handle connection to the Otii server.

Type:: OtiiConnection

__init__(recording_dict: dict, connection: OtiiConnection)

Parameters:

recording_dict (dict) – Dictionary with recording parameters.
connection (OtiiConnection) – Object to handle connection to the Otii server.

delete() → None: Delete the recording.

downsample_channel(device_id: str, channel: str, factor: int) → None

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

Parameters:

device_id (str) – ID of device capturing the data.
channel (str) – Name of the channel to downsample.
factor (int) – Factor to downsample with.

get_channel_data(device_id: str, channel: str, index: int, count: int, strip: bool = True) → dict

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

For available channels see Arc.enable_channel()

Parameters:

device_id (str) – ID of device to get data from.
channel (str) – Name of the channel to get data from.
index (int) – Start position for fetching data, first value at index 0.
count (int) – Number of data entries to fetch.
strip (bool) – Strip control data from log channel, defaults to True.

Returns:

Data for analog channels:

{
    # Data type is analog
    "data_type": 'analog',
    # Timestamp in seconds of first sample
    "timestamp": 3.250
    # Interval in seconds between each sample
    "interval": 0.00025,
    # Array of samples
    "values": [0.002453, 0.002675, 0.001945, 0.002444]
}

Data for digital channels:

{
    # Data type is digital
    "data_type": "digital",
    # Array of values
    "values": [{
        # Timestamp in seconds
        "timestamp": 0.001,
        # Digital value
        "value": true
    }, {
        "timestamp": 2.132,
        "value": false
    }]
}

Data for the rx channel:

{
    # Data type is log
    "data_type": "log",
    "values": [{
        # Timestamp in seconds
        "timestamp": 0.001,
        # Log text
        "value": "Device booting"
    }, {
        "timsestamp": 2.132,
        "value": "Going to sleep"
    }]
}

get_channel_data_count(device_id: str, channel: str) → int

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

For available channels see Arc.enable_channel()

Parameters:

device_id (str) – ID of device to get data from.
channel (str) – Name of the channel to get data from.

Returns:

Number of data entries in the channel.

Return type:

int

get_channel_data_index(device_id: str, channel: str, timestamp: float) → int

Get the index of a data entry in a channel for a given timestamp for the recording.

For available channels see Arc.enable_channel()

Parameters:

device_id (str) – ID of device to get data from.
channel (str) – Name of the channel to get data from.
timestamp (float) – Timestamp to get index of in seconds (s).

Returns:

Index of data entry at the timestamp.

Return type:

int

get_channel_info(device_id: str, channel: str) → dict

Get information for a channel in the recording.

For available channels see Arc.enable_channel()

Parameters:

device_id (str) – ID of device to get info from.
channel (str) – Name of the channel to get info from.

Returns:

Recording info:

{
    # The offset of the recording in seconds.
    "offset": 0.0,
    # The start of the recording in seconds.
    "from": 0.0
    # The end of the recording in seconds.
    "to": 5.34,
    # The sample rate of the recording.
    "sample_rate": 4000
}

Examples

basic_measurement.py

get_channel_statistics(device_id: str, channel: str, from_time: float, to_time: float) → dict

Get statistics for a channel for a given time interval in the recording.

For available channels see Arc.enable_channel()

Parameters:

device_id (str) – ID of device to get data from.
channel (str) – Name of the channel to get data from.
from_time (float) – Selection start in seconds.
to_time (float) – Selection end in seconds.

Returns:

Recording statistics:

{
    # The minimum value in the selected interval.
    "min": -0,00565853156149387,
    # The maximum value in the selected interval.
    "max": 0,476982802152634,
    # The average value in the selected interval.
    "average": 0,0561770809812117,
    # The energy consumed in the interval (if applicable).
    "energy": 0,000290418408670424
}

get_offset() → float

Get the offset of the recording

Returns:: The offset of the recording
Return type:: float

rename(name: str) → None

Change the name of the recording.

Parameters:: name (str) – New name of recording.

set_offset(offset: float) → None

Set the offset of the recording

Parameters:: offset (int) – The new offset to apply in microseconds.

battery_emulator

class otii_tcp_client.battery_emulator.BatteryEmulator(battery_emulator_id, connection)

Class to define a Battery Emulator object.

id

Id of the battery emulator.

Type:: string

connection

Object to handle connection to the Otii server.

Type:: OtiiConnection

__init__(battery_emulator_id, connection)

Parameters:

battery_emulator_id (string) – Id of the battery emulator.
connection (OtiiConnection) – Object to handle connection to the Otii server.

get_parallel()

Get current number of emulated batteries in parallel.

Returns:: Number of batteries in parallel.
Return type:: int

get_series()

Get current number of simulated batteries in series.

Returns:: Number of batteries in series.
Return type:: int

get_soc()

Get State of Charge.

Returns:: State of charge in percent.
Return type:: float

get_soc_tracking()

Get current state of battery emulator State of Charge tracking.

Returns:: True if State fo Charge tracking is enabled, False if disabled.
Return type:: bool

get_used_capacity()

Get current battery emulator used capacity.

Returns:: Used capacity in coulomb (C).
Return type:: float

set_soc(value)

Set State of Charge.

Parameters:: value (float) – State of charge in percent

set_soc_tracking(enable)

Set State of Charge tracking.

Parameters:: enable (bool) – True to enable State of Charge tracking, False to disable.

set_used_capacity(value)

Set used capacity.

Parameters:: value (float) – Capacity used in coulombs (C), multiply mAh by 3.6 to get C.

update_profile(battery_profile_id, mode)

Update battery profile.

Parameters:

battery_profile_id (string) – Id of battery profile, as returned by otii.get_battery_profiles.
mode (string) – “keep_soc” or “reset”