Skip to main content
Deutsch 简体中文

DOSE-X API Documentation

 

The DOSE-X API Documentation is available in the DOSE-X Reference Guide:

DOSE-X Reference Guide including API documentation

 

Please also find the API documentation for DOSE-X below:

 

Availability

To access the device remotely the item Remote Access has to be initially enabled on the touchscreen UI
using System Settings > Network and turning on Allow remote control.

  • The device exposes a WebUI on the default http(s) ports 80 and 443.
  • The WebUI uses the API exposed as websocket on port 8081 (ws) and 8083 (wss).
  • The device is discoverable using zeroconf providing the services _ibadose-x._tcp and _ibadosex-
    tls._tcp. For that a mdns service is running on port 5353/udp.

General Message Structure

  1. The server exposes a websocket API.
  2. The message format follows a simple format which is json based.
  3. Every message has a mandatory field cmd to identify its purpose often followd by a values field.

Authentication

There are two access levels available to the user:

  • User (no authentication needed)
  • Admin

Sessions

The User session ends when the websocket connection is closed.

 

Control Token

The User session ends when the websocket connection is closed.

# Req
{"cmd": "control", "value": "request"}
# Resp
{"cmd":"remote_status","values":{"blocked":false,"control":true}}

 

Admin authentication

The Admin password is set by the user on initial setup at the customer. It is required to access certain
functionality like editing libraries or changing network configurations.

# Req
{ "cmd": "login", "password": "fooobar" }
# Resp success
{ "cmd": "login", "result": true }
# Resp error
{ "cmd": "login", "result": false }

 

Resetting the Admin password

The Admin Password can be reset by sending the recovery_token instead of the password.
The token is generated using the following algorithm and requires the knowledge of the seed.
base64.b64encode(hashlib.sha512(seed+b'recovery').digest())[0:10].

# Req
{ "cmd": "login", "password": "recovery_token" }
# Resp
{ "cmd": "value_update", "values": { "adminPasswordIsSet": false } }

 

Configuration Items

The central concept of the API are Configuration Items. Most Settings and States are represented using
these commands.
Reading Configuration Items:

# Resp
{ "cmd": "get_values",
"values": [ "key1", "key2", ...]
}
# Resp
{ "cmd":"value_init",
"values": {"key1": "value",
"key2": {"value": 1, "unit": "s"},
...}
}

Setting Configuration Items:

# Req
{ "cmd": "change_values",
"values": [ "key1": "value",
"key2": "value",
...}
}
# Req
{ "cmd": "value_update",
"values": [ "key1": "value",
"key2": "value",
...}
}
  • The calling client always gets a value_update with the updated values.
  • Unknown keys or illegal values are silently ignored.
  • value_updates might be broadcasted by the system when values change.

Functional Blocks

Functional Blocks are commands that are connected.

Properties of the Firmware

All fields are read-only.

Device FRAM

 

Measurement

The DOSE-X has a constantly measuring electrometer. Therefore, the device is permanently calculating the average current. Measurements are using the integrator to integrate a number of currents.

Peak Value

The API is sending the measured Peak Current every 200ms.
{"cmd":"measurement_data", "values":{"peakValue": 3.051757735406113e-10}}

Measurement

Measurement Related Properties
Properties changeable when token was acquired.

Read-only properties:



Start a Measurement
If autoReset is set to false the integrator will start with the result of the previous
measurement.

-> {"cmd": "measurement", "value": "start"}

Measurement Data
When a Measurement is running an update is sent every 500ms. The data may contain additional fields for UI purposes which can be ignored.
Measurement Data in Charge Mode:

{"cmd":"measurement_data",
"values":
{ "charge":-2.3780011453311807e-09,
"current":-2.698900403281331e-10,
"measurementRunning":true,
"measuringTime":8811
}
}

Stop a Measurement

This always stops the current Measurement. In Manual-Mode this is the only way to stop it.

-> {"cmd": "measurement", "value": "stop"}

Reset Integrator
Reset the Data of the last Measurement. If autoReset is set to false this command has to be used to Zero
the integrator.

-> {"cmd": "measurement", "value": "reset"}

Background Measurement
Trigger a Background Measurement. The Measurement is running for the configured
'backgroundmeasurementTime'.
This behaves just like a normal measurement with two differences:

  1. No Background is subtracted
  2. The resulting Average Current is used as Background for the selected Range
-> {"cmd": "measurement", "value": "start_background"}

Libraries

The History and the Libraries behave similar. Most Noticable difference is that the user can't add or edit
entries in the Measurement History.

History and Libraries can be read by requesting the according Configuration Item:

1. No Background is subtracted
2. The resulting Average Current is used as Background for the selected Range

  • `measurementHistory`
  • `detector`
  • `machine`

Detector Library

Removing a measurement requires an array of ids send.

```json
# Req
{"cmd":"delete_measurement","values":[419]}
# Resp
{"cmd":"value_update","values":{"measurementHistory":[...]}
}
```


Machine Library

To edit a Library item the `library_update` command is used.

The Client can either request a template entry by using `get_new_detector`/`get_new_machine`
or by editing an existing entry. It is highly recommended to use the json received from the api instead of
manually composing an entry.

To remove an entry the `library_remove` is used.

 

List of Configuration Items

 

 

 

List of Known Commands