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	Yes	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.
`powerLimit`	v1-portParam	No	Power limit for the device.
`powerLimitMax`	v1-portParam	No	Maximum power limit for the device.
`inputVoltage`	v1-portParam	No	Input voltage to the device.
`inputCurrent`	v1-portParam	No	Input current to the device.
`inputVoltageUnregulated`	v1-portParam	No	Unregulated input voltage to the device.
`inputCurrentUnregulated`	v1-portParam	No	Unregulated input current to the device.
`inputPowerSource`	string	No	Source of input power for the device.
`hdbaset`	Array<v1-hdbasetInfo>	No	Array of HDBaseT information for the device.
`poe`	Array<v1-poeInfo>	No	Array of POE information for the 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.
`cableInfo`	v1-cableInfo	No	If set, the available cable information
`allocatedPower`	v1-portParam	No	Power allocated to this port.
`availablePower`	v1-portParam	No	Power available to this port.
`powerLimit`	v1-portParam	No	Power limit for this port.
`vbusAccumulatedPower`	v1-portParam	No	Accumulated VBUS power consumption for this port.
`vconnAccumulatedPower`	v1-portParam	No	Accumulated VCONN power consumption for 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
`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`, `USBCSwitchPro`, `MTMDAQ2`, `MTMLoad1`, `USBHub3c`, `USBExt3c`, `PD3M`, `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-cableInfo¶

Name	Value
Type	Object
description	Object containing available cable information

Name	Type	Mandatory	Description
`orientation`	v1-cableOrientation	No	If available, the current cable orientation
`maxSpeed`	v1-cableMaxSpeed	No	If available, the maximum speed the cable is capable of
`type`	v1-cableType	No	If available, the type of cable
`maxVoltage`	v1-cableMaxVoltage	No	If available, the maximum voltage the cable is capable of
`maxCurrent`	v1-cableMaxCurrent	No	If available, the maximum current the cable is capable of

v1-cableOrientation¶

Name	Value
Type	string
description	Enumeration of all possible cable orientations
Enumerations	`Unknown`, `CC1`, `CC2`

v1-cableMaxSpeed¶

Name	Value
Type	string
description	Enumeration of all possible cable speeds
Enumerations	`Unknown`, `USB 2.0`, `USB 3.2 Gen 1`, `USB 3.2 / USB 4 Gen 2`, `USB 4.0 Gen 3`, `USB 4.0 Gen 4`

v1-cableMaxVoltage¶

Name	Value
Type	string
description	Enumeration of all possible cable voltage limitations
Enumerations	`Unknown`, `20V`, `30V`, `40V`, `50V`

v1-cableMaxCurrent¶

Name	Value
Type	string
description	Enumeration of all possible cable current limitations
Enumerations	`Unknown`, `3A`, `5A`

v1-cableType¶

Name	Value
Type	string
description	Enumeration of all possible cable types
Enumerations	`Unknown`, `Passive`, `Active`

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.

v1-hdbasetInfo¶

Name	Value
Type	Object
description	Object containing HDBaseT information

Name	Type	Mandatory	Description
`index`	v1-uint8	Yes	HDBaseT interface index
`serialNumber`	string	No	HDBaseT device serial number
`firmwareVersion`	string	No	HDBaseT device firmware version
`state`	Array<v1-hdbasetState>	No	Array of HDBaseT state flags
`cableLength`	v1-portParam	No	Cable length in meters
`mseA`	v1-portParam	No	Mean Square Error for channel A in decibels
`mseB`	v1-portParam	No	Mean Square Error for channel B in decibels
`retransmissionRate`	string	No	Retransmission rate as a string
`encodingState`	v1-hdbasetEncodingState	No	Current encoding state
`linkUtilization`	v1-portParam	No	Link utilization as a percentage

v1-hdbasetState¶

Name	Value
Type	string
description	Enumeration of HDBaseT state flags
Enumerations	`Device Present`, `Link Up`

v1-hdbasetEncodingState¶

Name	Value
Type	string
description	Enumeration of HDBaseT encoding states
Enumerations	`Unknown`, `PAM-16`, `PAM-8`, `PAM-4`

v1-poeInfo¶

Name	Value
Type	Object
description	Object containing POE information

Name	Type	Mandatory	Description
`voltage`	v1-portParam	No	POE voltage
`current`	v1-portParam	No	POE current
`resistance`	v1-portParam	No	POE resistance
`mode`	v1-poePowerMode	No	POE power mode
`state`	v1-poePowerMode	No	POE power state
`pair12DetectionStatus`	v1-poeDetectionStatus	No	Detection status for pairs 1/2
`pair34DetectionStatus`	v1-poeDetectionStatus	No	Detection status for pairs 3/4
`pair12SourcingClass`	v1-poeClassification	No	Sourcing class for pairs 1/2
`pair34SourcingClass`	v1-poeClassification	No	Sourcing class for pairs 3/4
`pair12DiscoveredClass`	v1-poeClassification	No	Discovered class for pairs 1/2
`pair34DiscoveredClass`	v1-poeClassification	No	Discovered class for pairs 3/4
`pair12RequestedClass`	v1-poeClassification	No	Requested class for pairs 1/2
`pair34RequestedClass`	v1-poeClassification	No	Requested class for pairs 3/4

v1-poePowerMode¶

Name	Value
Type	string
description	Enumeration of POE power modes
Enumerations	`Off`, `PSE`, `PD`, `Auto`

v1-poeDetectionStatus¶

Name	Value
Type	string
description	Enumeration of POE detection statuses
Enumerations	`Unknown`, `Short Circuit`, `Open Circuit`, `Low Resistance`, `High Resistance`, `Valid`, `Switch Failure`

v1-poeClassification¶

Name	Value
Type	string
description	Enumeration of POE classifications
Enumerations	`Unknown`, `Class 0`, `Class 1`, `Class 2`, `Class 3`, `Class 4`, `Class 4+`, `Class 5 4P SS`, `Class 5 4P DS`, `Class 6`, `Class 7`, `Class 8`, `Mismatch`, `OverCurrent`

Examples¶

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

import requests
import json
response = requests.get('http://127.0.0.1:9005/api/v1/acronameDevicesState')
json_data = response.json()
print(json.dumps(json_data, indent=4))

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