brainstem Endpoint

This reference builds on understanding of the BrainStem system. If you would like to get started using BrainStem, please see the following sections of the Reference documentation:

• BrainStem Overview

• BrainStem Terminology

• Getting Started with the BrainStem.

BrainStem GET commands are implemented with HTTP GET calls, and SET commands are implemented with HTTP PUT calls. The entity and operation fields are mapped directly to BrainStem API calls, minus the get and set prefixes on the operations.

The parameters for the command are given as slash-separated path entries:

• GET http://<IPADDRESS>:<PORT>/api/v1/brainstem/<SERIALNUM>/<ENTITY>/<INDEX>/<COMMAND>

• GET http://<IPADDRESS>:<PORT>/api/v1/brainstem/<SERIALNUM>/<ENTITY>/<INDEX>/<COMMAND> {BODY}

BrainStem Request Parameters

Parameter	Request Type	Description
IPADDRESS	GET, PUT	IP Address of BrainD server hosting RESTful endpoints.
PORT	GET, PUT	Port that BrainD server is listening for connections. Default is 9005.
SERIALNUM	GET, PUT	Serial Number of the BrainStem device being accessed
ENTITY	GET, PUT	BrainStem Entity, e.g. system, temperature, digital.
INDEX	GET, PUT	Entity Index
COMMAND	GET, PUT	Operation to perform on entity without get or set prefix, e.g. inputvoltage, currentlimit, name.
BODY	PUT	HTTP PUT payload, matching PUT Request JSON Schema

Note

The following BrainStem Entities are unsupported at this time: app, i2c, powerDelivery

Examples

GET Command

BashPython

curl http://127.0.0.1:9005/api/v1/brainstem/3C43352C/system/0/inputvoltage

The output will be similar to the following:

{
    "timestamp": "2023-09-20T17:53:32.480Z",
    "request": {
        "endpointName": "/api/v1/brainstem/3C43352C/system/0/inputvoltage",
        "parameters": {}
    },
    "response": {
        "value": 22974139,
        "rawValue": 22974139
    }
}

SET Command

BashPython

curl -X PUT -d '{"value": "New Port Name"}' http://127.0.0.1:9005/api/v1/brainstem/3C43352C/port/2/name

The output will be similar to the following:

{
    "timestamp": "2023-09-20T17:55:15.134Z",
    "request": {
        "endpointName": "/api/v1/brainstem/3C43352C/port/2/name",
        "parameters": {
            "value": "New Port Name"
        }
    },
    "response": {}
}

GET Command with no response

BashPython

curl http://127.0.0.1:9005/api/v1/brainstem/3C43352C/system/0/save

The output will be similar to the following:

{
    "timestamp": "2023-09-20T17:57:05.245Z",
    "request": {
        "endpointName": "/api/v1/brainstem/3C43352C/system/0/save",
        "parameters": {}
    },
    "response": {}
}

JSON Schema for GET Response Object

The following table lists a JSON Schema for the response object.

Download the raw JSON Schema file for this response: get_brainstem_response.json

Object Fields of Get Brainstem Response

Name	Type	Mandatory	Description
rawValue	v1-rawValue	Yes
value	string or number	No	If appropriate, a user-friendly formatted value.
units	v1-units	No

v1-aErr

Name	Value
Type	string
description	Enumeration of all possible error results
Enumerations	aErrNone, aErrMemory, aErrParam, aErrNotFound, aErrFileNameLength, aErrBusy, aErrIO, aErrMode, aErrWrite, aErrRead, aErrEOF, aErrNotReady, aErrPermission, aErrRange, aErrSize, aErrOverrun, aErrParse, aErrConfiguration, aErrTimeout, aErrInitialization, aErrVersion, aErrUnimplemented, aErrDuplicate, aErrCancel, aErrPacket, aErrConnection, aErrIndexRange, aErrShortCommand, aErrInvalidEntity, aErrInvalidOption, aErrResource, aErrMedia, aErrAsyncReturn, aErrOperation, aErrUnknown

v1-units

Name	Value
Type	string
description	Allowed and recognized units for a value.
Enumerations	volts, millivolts, microvolts, amperes, milliamperes, microamperes, coulombs, millicoulombs, microcoulombs, seconds, milliseconds, microseconds, nanoseconds, kilowatts, watts, milliwatts, microwatts, kilowatt-hours, watt-hours, milliwatt-hours, microwatt-hours

v1-uint32

Name	Value
Type	integer
description	Unsigned 32-bit integer
minimum	0
maximum	4294967295

v1-rawValue

Name	Value
Type	v1-uint32 or Array<v1-uint32>
description	Unformatted return value from the device.

v1-error

Name	Value
Type	Object
description	Error containing an acroname error

Name	Type	Mandatory	Description
errorCode	v1-aErr	Yes	Acroname error code
errorMessage	string	No	A human-readable message to describe the context of the error.

JSON Schema for PUT Request Object

The following table lists a JSON Schema for the response object.

Download the raw JSON Schema file for this response: put_brainstem_payload_v1.json

Object Fields of Put Brainstem Payload (v1)

Name	Type	Mandatory	Description
value	integer or string or boolean or Array<integer or string>	Yes	Value to set on the Device.

JSON Schema for PUT Response Object

The following table lists a JSON Schema for the response object.

Download the raw JSON Schema file for this response: put_brainstem_response.json

Object Fields of Put Brainstem Response

Name	Type	Mandatory	Description
errorCode	v1-aErr	Yes	Acroname error code
errorMessage	string	No	A human-readable message to describe the context of the error.
- or -
thisMessageLeftIntentionallyBlank	null	No

v1-aErr

Name	Value
Type	string
description	Enumeration of all possible error results
Enumerations	aErrNone, aErrMemory, aErrParam, aErrNotFound, aErrFileNameLength, aErrBusy, aErrIO, aErrMode, aErrWrite, aErrRead, aErrEOF, aErrNotReady, aErrPermission, aErrRange, aErrSize, aErrOverrun, aErrParse, aErrConfiguration, aErrTimeout, aErrInitialization, aErrVersion, aErrUnimplemented, aErrDuplicate, aErrCancel, aErrPacket, aErrConnection, aErrIndexRange, aErrShortCommand, aErrInvalidEntity, aErrInvalidOption, aErrResource, aErrMedia, aErrAsyncReturn, aErrOperation, aErrUnknown

v1-error

Name	Value
Type	Object
description	Error containing an acroname error

Name	Type	Mandatory	Description
errorCode	v1-aErr	Yes	Acroname error code
errorMessage	string	No	A human-readable message to describe the context of the error.