acronameDevicesState Endpoint

The acronameDevicesState endpoint provides telemetry and state information for all of the attached Acroname devices on the host system. It provides USB connection information, custom names, and device version information for each port on the device.

There are no input parameters to this endpoint. It will return a JSON array of devices, or error, encapsulated in a transaction envelope.

JSON Schema for Response Object

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

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

Object Fields of Acroname Devices State Response

Name	Type	Mandatory	Description
timestamp	v1-timestamp	Yes	Time and date that this object was created.
sequence	v1-uint32	Yes	Sequence counter that increments on each message sent.
brainstemVersion	v1-version	Yes	Version of the BrainStem library for this object.
acronameDevices	Array<Object>	Yes	Array containing all the available Acroname devices on the system.

Object Fields of acronameDevices[]

Name	Type	Mandatory	Description
serialNumber	v1-serialNumber	Yes	Acroname Serial Number
firmwareVersion	v1-version	Yes	Firmware version that is running on the device.
model	v1-model	Yes	Model Name of the device.
customName	string	No	If set, a user-defined name for the device.
upstreamPort	v1-uint8	No	Currently active upstream port index.
upstreamPortSelectionIsAutomatic	boolean	Yes	Is upstream port selected automatically.
ports	Array<Object>	No	Object representing a single port on a device.

Object Fields of acronameDevices[].ports[]

Name	Type	Mandatory	Description
index	v1-uint8	Yes	Physical Port Number on device. This may include upstream ports, control ports, etc.
physicalName	string	Yes	Description of the port type and number.
customName	string	No	If set, a user-defined name for the port.
speed	string	No	Current data speed of the port.
roles	Array<v1-dataRole>	Yes	All supported data roles of the port.
currentDataRole	v1-dataRole	Yes	Current data role of the port.
enabled	boolean	No	Whether or not the port is enabled.
voltage	v1-portParam	No	Voltage measurement from this port.
current	v1-portParam	No	Current measurement from this port.

v1-timestamp

Name	Value
Type	string
description	String containing a ISO8601 timestamp (YYYY-MM-DDTHH:MM:SS.mmmZ
Regular Expression	^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3,6}Z$

v1-serialNumber

Name	Value
Type	string
description	Hexadecimal representation of an Acroname device.
Regular Expression	^(0x)?[A-Fa-f0-9]{8}$

v1-version

Name	Value
Type	Object
description	Object representing a <major>.<minor>.<patch> semantic version.

Name	Type	Mandatory	Description
major	v1-uint8	Yes
minor	v1-uint8	Yes
patch	v1-uint8	Yes

v1-model

Name	Value
Type	string
description	Enumeration of all supported Acroname devices.
Enumerations	USBStem, EtherStem, MTMIOSerial, MTMPM1, MTMEtherStem, MTMUSBStem, USBHub2x4, MTMRelay, USBHub3p, MTMDAQ1, USBCSwitch, MTMDAQ2, MTMLoad1, USBHub3c, Unknown

v1-dataRole

Name	Value
Type	string
description	Enumeration of all supported data roles for a port.
Enumerations	Disabled, Upstream, Downstream, Control, Unknown

v1-portParam

Name	Value
Type	Object
description	Object containing a data parameter with units and scale values.

Name	Type	Mandatory	Description
rawValue	number	Yes	Unformatted return value from the device.
value	number	Yes	If appropriate, a user-friendly formatted value.
units	v1-units	Yes	If appropriate, a user-friendly unit string.

v1-uint8

Name	Value
Type	integer
description	Unsigned 8-bit integer
minimum	0
maximum	255

v1-uint32

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

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-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.

Examples

BashPython

curl http://127.0.0.1:9005/api/v1/acronameDevicesState

The output will be similar to the following:

{
    "timestamp": "2023-09-20T17:24:24.428Z",
    "request": {
        "endpointName": "/api/v1/acronameDevicesState",
        "parameters": {}
    },
    "response": {
        "timestamp": "2023-09-20T17:24:24.108Z",
        "sequence": 2563,
        "brainstemVersion": {
            "major": 2,
            "minor": 10,
            "patch": 0
        },
        "acronameDevices": [
            {
                "serialNumber": "0x3C43352C",
                "firmwareVersion": {
                    "major": 2,
                    "minor": 10,
                    "patch": 0
                },
                "model": "USBHub3c",
                "upstreamPort": 0,
                "upstreamPortSelectionIsAutomatic": true,
                "ports": [
                    {
                        "index": 0,
                        "physicalName": "Port 0",
                        "speed": "5 Gbps",
                        "roles": [
                            "Upstream",
                            "Downstream"
                        ],
                        "currentDataRole": "Upstream",
                        "enabled": true,
                        "voltage": {
                            "value": 5.207519,
                            "units": "volts",
                            "rawValue": 5207519
                        },
                        "current": {
                            "value": 0.00061,
                            "units": "amperes",
                            "rawValue": 610
                        }
                    },
                    {
                        "index": 1,
                        "physicalName": "Port 1",
                        "speed": "Unknown",
                        "roles": [
                            "Upstream",
                            "Downstream"
                        ],
                        "currentDataRole": "Downstream",
                        "enabled": true,
                        "voltage": {
                            "value": 0.0,
                            "units": "volts",
                            "rawValue": 0
                        },
                        "current": {
                            "value": 0.000305,
                            "units": "amperes",
                            "rawValue": 305
                        }
                    },
                    <additional ports ...>
                ]
            }
        ]
    }
}