Mainboard (BMC)

Mainboard RESTful API documentation

This API is not final!

Generic

Base URL:

<HOSTNAME>/api/bmc/<version>/

Version check and device selection

See Version check and device selection

Error response

See Error Response

Voltage

Returns the voltage in millivolt.

Request:

Method: GET
URL: <HOSTNAME>/api/bmc/<version>/<slot>/voltage

Parameters:

No body parameters

Response:

{
  "voltage_1v8": <mV>,
  "voltage_rtc": <mV>
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/voltage

Response:

{
  "voltage_1v8": 1788,
  "voltage_rtc": 2949
}

Temperature

Returns the temperature in Celsius. The “ntc_0” shows the temperature emitted by the SoC while the “ntc_1” shows the ambient temperature. The unit is degree Celsius.

Location on the board:

ntc_0: close to the SoC/CPU

ntc_1: close to the buzzer/version information (temp. typically lower)

Request:

Method: GET
URL: <HOSTNAME>/api/bmc/<version>/<slot>/temperature

Parameters:

No body parameters

Response:

{
  "ntc_0": <Temp. in Celsius (float)>,
  "ntc_1": <Temp. in Celsius (float)>
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/temperature

Response:

{
  "ntc_0": 38.703,
  "ntc_1": 29.587
}

Watchdog

Controls the internal watchdog function which hard resets the device if the timeout expires.

GET /watchdog

Returns the timeout values in milliseconds.

timeout: current timeout setting

timeout_left: time left until reset

shutdown_timeout: time after the device is reset if a shutdown was initialized

emergency_mode: shows if the device is in emergency mode (storage corrupted, no r/w)

Request:

Method: GET
URL: <HOSTNAME>/api/bmc/<version>/<slot>/watchdog

Parameters:

No body parameters

Response:

{
  "timeout": <ms>,
  "timeout_left": <ms>,
  "shutdown_timeout": <ms>,
  "emergency_mode": <bool>
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/watchdog

Response:

{
  "timeout": 0,
  "timeout_left": 0,
  "shutdown_timeout": 600000,
  "emergency_mode": false
}

POST /watchdog

Enables the watchdog timeout. The timeout is disabled after reset if the config is not saved.

timeout: timeout setting in milliseconds Value must be >= 1000 and <= 600000, 0 means disabled

Request:

Method: POST
URL: <HOSTNAME>/api/bmc/<version>/<slot>/watchdog

Parameters:

{
  "timeout": <ms>,
}

Response:

{
  "status": "success"
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/watchdog --header "Content-Type: application/json" --request POST --data '{"timeout": 0}'

Response:

{
  "status": "success"
}

POST /watchdog/sw_shutdown_timeout

Changes the shutdown timeout. The timeout is always stored persistent.

timeout: timeout setting in milliseconds Value must be >= 10000 and <= 600000

Request:

Method: POST
URL: <HOSTNAME>/api/bmc/<version>/<slot>/watchdog/sw_shutdown_timeout

Parameters:

{
  "timeout": <ms>,
}

Response:

{
  "status": "success"
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/watchdog/sw_shutdown_timeout --header "Content-Type: application/json" --request POST --data '{"timeout": 100000}'

Response:

{
  "status": "success"
}

POST /watchdog/shutdown

Starts the shutdown watchdog counter. This is the same procedure as triggered by the hardware switch.

Request:

Method: POST
URL: <HOSTNAME>/api/bmc/<version>/<slot>/watchdog/shutdown

Parameters:

{
  "shutdown": "start",
}

Response:

{
  "status": "success"
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/watchdog/shutdown --header "Content-Type: application/json" --request POST --data '{"shutdown": "start"}'

Response:

{
  "status": "success"
}

GET /watchdog/alive

Resets the watchdog counter.

Request:

Method: GET
URL: <HOSTNAME>/api/bmc/<version>/<slot>/watchdog/alive

Parameters:

No body parameters

Response:

{
  "status": "success"
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/watchdog/alive

Response:

{
  "status": "success"
}

GET /watchdog/save

Saves the current timeout configuration persistent.

Request:

Method: GET
URL: <HOSTNAME>/api/bmc/<version>/<slot>/watchdog/save

Parameters:

No body parameters

Response:

{
  "status": "success"
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/watchdog/save

Response:

{
  "status": "success"
}

USB Hub

Controls the USB hub states.

GET /usbhub

Returns the states of all ports and the hub itself.

can be “enabled”, “disabled” or “not available”.

Request:

Method: GET
URL: <HOSTNAME>/api/bmc/<version>/<slot>/usbhub

Parameters:

No body parameters

Response:

{
  "hub_state": <state>,
  "port_slot_2": <state>,
  "port_slot_3": <state>,
  "port_slot_4": <state>,
  "port_slot_5": <state>,
  "port_slot_6": <state>,
  "port_slot_7": <state>,
  "port_slot_8": <state>
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/usbhub

Response:

{
  "hub_state": "enabled",
  "port_slot_2": "enabled",
  "port_slot_3": "enabled",
  "port_slot_4": "enabled",
  "port_slot_5": "enabled",
  "port_slot_6": "enabled",
  "port_slot_7": "enabled",
  "port_slot_8": "not available"
}

POST /usbhub

Enables or disables the USB Hub. The /reset command must be used to apply the settings.
The state is boolean and can be true or false.

Request:

Method: POST
URL: <HOSTNAME>/api/bmc/<version>/<slot>/usbhub

Parameters:

{
  "state": boolean,
}

Response:

{
  "status": "success"
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/usbhub --header "Content-Type: application/json" --request POST --data '{"state": true}'

Response:

{
  "status": "success"
}

POST /usbhub/port/

Enables or disables the port.
The /usbhub/reset command must be used to apply the settings.
The state is boolean and can be true or false.

Request:

Method: POST
URL: <HOSTNAME>/api/bmc/<version>/<slot>/usbhub/port/<number>

Parameters:

{
  "state": boolean,
}

Response:

{
  "status": "success"
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/usbhub/port/7 --header "Content-Type: application/json" --request POST --data '{"state": true}'

Response:

{
  "status": "success"
}

POST /usbhub/reset

Resets the USB Hub and applies the saved setting.
CAUTION: On reset all USB devices are disconnected and may drop their connection!

Request:

Method: POST
URL: <HOSTNAME>/api/bmc/<version>/<slot>/usbhub/reset

Parameters:

{
  "reset": "yes",
}

Response:

{
  "status": "success"
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/usbhub/reset --header "Content-Type: application/json" --request POST --data '{"reset": "yes"}'

Response:

{
  "status": "success"
}

USB Bootloader

Enables the USB Bootloader which allows to access the internal storage (SDCARD/EMMC) via the USB port.
The mode is activated after next reset.
A host device must be connected via USB cable and the USB Bootloader must be activated within 90 seconds otherwise the device will reset to normal mode.

“enabled” can be true or false ”timeout” must be <= 3600000 milliseconds

Request:

Method: POST
URL: <HOSTNAME>/api/bmc/<version>/<slot>/usb_bootloader

Parameters:

{
  "enabled": <boolean>,
  "timeout": <ms>,
}

Response:

{
  "status": "success"
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/usb_bootloader --header "Content-Type: application/json" --request POST --data '{"enabled": false, "timeout": 100000}'

Response:

{
  "status": "success"
}

Hard Reset

Hard resets the device.

Request:

Method: POST
URL: <HOSTNAME>/api/bmc/<version>/<slot>/hard_reset

Parameters:

{
  "reset": "yes"
}

Response:

{
  "status": "success"
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/hard_reset --header "Content-Type: application/json" --request POST --data '{"reset": "yes"}'

Response:

{
  "status": "success"
}

Buzzer

Controls the integrated buzzer.

“mode” can be:
0 = Internal sounds are disabled
1 = Internal sounds are enabled
2 = Sound 1 played for duration
3 = Sound 2 played for duration
4 = Sound 3 played for duration
5 = Sound 4 played for duration

“duration” must be >= 1 and <= 1000 (milliseconds)

Request:

Method: POST
URL: <HOSTNAME>/api/bmc/<version>/<slot>/buzzer

Parameters:

{
  "mode": <int>,
  "duration": <ms>
}

Response:

{
  "status": "success"
}

Example

Request:

curl http://<HOSTNAME>/api/bmc/0.1/0/buzzer --header "Content-Type: application/json" --request POST --data '{"mode": 4, "duration": 100}'

Response:

{
  "status": "success"
}


Examples

Simple usage examples

Last modified October 10, 2021