Control APIs

Control the Amplifier over TCP and HTTP using JSON-RPC 2.0

This is a preliminary api documentation, subject to change

Subsections of Control APIs

JSON RPC 2.0 API

This section describes the communication protocol between the control system and the 4140PWRR3 using RPC calls using the JSON-RPC 2.0 protocol

Definitions

Caution

Commands must be formatted as defined in the JSON-RPC 2.0 protocol
All commands sent over TCP transport must end with <LF>
All replies are formatted as defined in the JSON-RPC 2.0 protocol
All replies over TCP transport end up with <LF>
<LF> stands for “line feed”, corresponding hex is 0x0A

Transport protocols

JSON-RPC 2.0 commands can flow over different transport protocols, they need to be enabled in the config file of the installed api service. Per default they might not be enabled.

Transport Config Datatype Example Supported Versions
TCP jrpc2TCPInterface string eth1 >v1.0.1
TCP jrpc2TCPPort int 64823 >v1.0.1
TCP jrpc2HTTPInterface string eth1 >v1.0.1
TCP jrpc2HTTPPort int 64880 >v1.0.1

In subsequent pages all methods are described that can be used.

Concurrency

All JSON-RPC 2.0 services do support asynchronous message processing. 3rd party control Systems must keep tracking of the id’s to determine whether a request was successful or not

TCP transport

Any TCP capable application can be used to test commands. Do not forget to end up with <LF>

HTTP transport

The body of the HTTP POST request must contain the complete JSON-RPC request message, encoded with Content-Type: application/json. Either a single request object or a list of request objects is supported. If the request completes, whether or not there is an error, the HTTP response is 200 (OK) for ordinary requests or 204 (No Response) for notifications, and the response body contains the JSON-RPC response. If the HTTP request method is not “POST”, 4140PWRR3 reports 405 (Method Not Allowed). If the Content-Type is not application/json, 4140PWRR3 reports 415 (Unsupported Media Type).

Test from a linux shell:
curl -i -X POST -H ‘Content-Type: application/json’ -d ‘{“jsonrpc”:“2.0”,“id”:1,“method”:“rpc.serverInfo”}’ http://host:64880

Subsections of JSON RPC 2.0 API

amplifier

amplifier.channel.set (channelSet)

Enable or disable, mute or unmute a amplifier channel

Caution

A hardware limitation only allows stereo channel pairs to be switched on the 2140pwrr3.

  • Channel 1 & 2 will power on/off together
Caution

A hardware limitation only allows stereo channel pairs to be muted on the 2140pwrr3.

  • Channel 1 & 2 will mute/unmute together

Request

Method Param Value Comment Supported Versions
amplifier.channelSet >v1.0.1
channel 1,2,3,4 Channel selection >v1.0.1
power 0,1 Power on (1) or off (0) >v1.0.1
mute 0,1 Mute (1) or unmute (0) >v1.0.1
amplifier.channel.set >=v1.0.14
channel 1,2,3,4 Channel selection >=v1.0.14
power 0,1 Power on (1) or off (0) >=v1.0.14
mute 0,1 Mute (1) or unmute (0) >=v1.0.14
​
{"jsonrpc":"2.0","id":1,"method":"amplifier.channelSet","params":{"channel":1,"power":1}}

{"jsonrpc":"2.0","id":1,"method":"amplifier.channel.set","params":{"channel":1,"power":1}}
​
{"jsonrpc":"2.0","id":1,"method":"amplifier.channelSet","params":{"channel":1,"power":1}}

{"jsonrpc":"2.0","id":1,"method":"amplifier.channel.set","params":{"channel":1,"power":1}}
​
{"jsonrpc":"2.0","id":1,"method":"amplifier.channelSet","params":{"channel":1,"mute":1}}

{"jsonrpc":"2.0","id":1,"method":"amplifier.channel.set","params":{"channel":1,"mute":1}}
​
{"jsonrpc":"2.0","id":1,"method":"amplifier.channelSet","params":{"channel":1,"power":1,"mute":0}}

{"jsonrpc":"2.0","id":1,"method":"amplifier.channel.set","params":{"channel":1,"power":1,"mute":0}}

Reply

Result Comment
null null means acknowledged, no error
​
{"jsonrpc":"2.0","id":1,"result":null}

amplifier.channel.get (channelGet)

Get the status of an amplifier channel

Request

Method Param Value Comment Supported Versions
amplifier.channelGet >v1.0.1
amplifier.channel.get >=v1.0.14
channel 1,2,3,4 Channel selection >v1.0.1
​
{"jsonrpc":"2.0","id":1,"method":"amplifier.channelGet","params":{"channel":1}}

{"jsonrpc":"2.0","id":1,"method":"amplifier.channel.get","params":{"channel":1}}

Reply

Result Key Comment
channel status
power 1 if channel was powered on, 0 if channel was powered off
mute 1 if channel was muted, 0 if channel was unmuted
error null if no error on channel otherwise error message
powerStatus 1 if channel is powered, otherwise 0
clip 1 if channel is clipping, otherwise 0
temp Temperature in °C
​
{"jsonrpc":"2.0","id":1,"result":{"channel":1,"power":1,"mute":0,"error":null,"powerStatus":1,"clip":0,"temp":42.3}}

amplifier.channels.subscribe (channelsSubscribe)

Subscribe all amplifier channels status push messages

Info

Enable push status messages

Pushed status messages having the same format as channelGet replies

Push messages over HTTP transport are not supported

Request

Method Param Value Comment Supported Versions
amplifier.channelsSubscribe >v1.0.1
amplifier.channels.subscribe >v1.0.14
​
{"jsonrpc":"2.0","id":1,"method":"amplifier.channelsSubscribe"}

{"jsonrpc":"2.0","id":1,"method":"amplifier.channels.subscribe"}

Reply

Result Comment
null null means acknowledged, no error
​
{"jsonrpc":"2.0","id":1,"result":null}

amplifier.channels.unsubscribe (channelsUnsubscribe)

Unsubscribe all amplifier channels status push messages

Request

Method Param Value Comment Supported Versions
amplifier.channelsUnsubscribe >v1.0.1
amplifier.channels.unsubscribe >=v1.0.14
​
{"jsonrpc":"2.0","id":1,"method":"amplifier.channelsUnsubscribe"}

{"jsonrpc":"2.0","id":1,"method":"amplifier.channels.unsubscribe"}

Reply

Result Comment
null null means acknowledged, no error
​
{"jsonrpc":"2.0","id":1,"result":null}

2140pwrr3

2140pwrr3.app.log.level.get

Get the log level for the 2140pwrr3 service running on the 2140pwrr3

Request

Method Param Value Comment Supported Versions
2140pwrr3.app.log.level.get >=v1.0.14
​
{"jsonrpc":"2.0","id":1,"method":"2140pwrr3.app.log.level.get"}

Reply

Result Comment
x Active log level
​
{"jsonrpc":"2.0","id":20,"result":{"level":3}}

2140pwrr3.app.log.level.set

Set the log level for sdm and associated processes

Request

Method Param Value Comment Supported Versions
2140pwrr3.app.log.level.set level 0-7 Log level to set >=v1.0.14
​
{"jsonrpc":"2.0","id":1,"method":"2140pwrr3.app.log.level.set","params":{"level":6}

Reply

Result Comment
null null means acknowledged, no error
​
{"jsonrpc":"2.0","id":1,"result":null}

api

api.app.log.level.get

Get the log level for the api service running on the api

Request

Method Param Value Comment Supported Versions
api.app.log.level.get >=v1.0.14
​
{"jsonrpc":"2.0","id":1,"method":"api.app.log.level.get"}

Reply

Result Comment
x Active log level
​
{"jsonrpc":"2.0","id":20,"result":{"level":3}}

api.app.log.level.set

Set the log level

Request

Method Param Value Comment Supported Versions
api.app.log.level.set level 0-7 Log level to set >=v1.0.14
​
{"jsonrpc":"2.0","id":1,"method":"api.app.log.level.set","params":{"level":6}

Reply

Result Comment
null null means acknowledged, no error
​
{"jsonrpc":"2.0","id":1,"result":null}

display

diplay.backlight.level.get

Get the log level for the api service running on the api

Request

Method Param Value Comment Supported Versions
diplay.backlight.level.get >=v1.0.14
​
{"jsonrpc":"2.0","id":1,"method":"diplay.backlight.level.get"}

Reply

Result Comment
x Active backlight level
​
{"jsonrpc":"2.0","id":20,"result":{"level":3}}

diplay.backlight.level.set

Set the backlight level

Request

Method Param Value Comment Supported Versions
diplay.backlight.level.set level 0-255 Level to set >=v1.0.14
​
{"jsonrpc":"2.0","id":1,"method":"diplay.backlight.level.set","params":{"level":6}

Reply

Result Comment
null null means acknowledged, no error
​
{"jsonrpc":"2.0","id":1,"result":null}

server

rpc.server.info.get (serverInfo)

Get all supported RCP methods

Request

Method Param Value Comment Supported Versions
rpc.serverInfo >1.0.1
rpc.server.info.get >=1.0.14
​
{"jsonrpc":"2.0","id":1,"method":"rpc.serverInfo"}

{"jsonrpc":"2.0","id":1,"method":"rpc.server.info.get"}

Reply

Result Key Comment
methods All supported methods that can be used by a 3rd party control system
counters Server counters
startTime Server start time
​
{
  "result": {
    "startTime": "2024-04-11T08:06:23.391135102Z",
    "metrics": {
      "bytes_written": 0,
      "rpc_requests": 1,
      "bytes_read": 55,
      "notifications_pushed": 0,
      "rpc_errors": 0,
      "servers_active": 2,
      "calls_pushed": 0
    },
    "methods": [
      "2140pwrr3-cf11.app.log.level.get","2140pwrr3-cf11.app.log.level.set","2140pwrr3-cf11.app.version.get","2140pwrr3.app.log.level.get","2140pwrr3.app.log.level.set","2140pwrr3.app.version.get","2140pwrr3.appLogLevelGet","2140pwrr3.appLogLevelSet","2140pwrr3.appVersionGet","amplifier.channel.get","amplifier.channel.set","amplifier.channelGet","amplifier.channelSet","amplifier.channels.subscribe","amplifier.channels.unsubscribe","amplifier.channelsSubscribe","amplifier.channelsUnsubscribe","api.app.log.level.get","api.app.log.level.set","api.app.version.get","api.appLogLevelGet","api.appLogLevelSet","api.appVersionGet","display.backlight.level.get","display.backlight.level.set","rpc.server.info.get","rpc.serverInfo","webui.app.log.level.get","webui.app.log.level.set","webui.app.version.get"]
  },
  "id": 1,
  "jsonrpc": "2.0"
}