05 MQTT Topics and UART Commands - Resinchem/Arylic-Amp-MQTT GitHub Wiki
MQTT Topics and UART Commands
Official documentation on the UART command set is scarce and not currently up-to-date with the latest firmware. During development, undocumented commands were discovered while other commands appear to have been removed or changed. The UART commands, and associated MQTT topics listed here are speficially for the AMP firmware version 4.6.x.36. Some UART commands may or may not work with either older or future versions of the firmware. Maybe at some point in the future Arylic will publish (and regularly update) an official document of UART commands.
UART Commands
While the primary purpose of this project is to provide and MQTT shell for most UART commands, knowing how to use UART commands may come in handy. One of the MQTT topics also allows you to issue a raw UART command to the amp should there be some commands (now or in the future) that do not have a corresponding MQTT topic.
UART commands generally consist of two parts:
A three character command and a value for that command, separated by a colon (:) and always ended with a semi-colon (;). The value can be a single value or possibly a multi-part value separated by colons (:). For example, a UART command to set the volume of the amp to 50, the following UART command would be used:
VOL:50;
If you wish to just return the current value or setting, issue the UART command without the colon and value, but you must still include the trailing semi-colon. For example, to use return the current volume setting, use the following UART command:
VOL;
Not all UART command can be be issued without a value. As a general rule, if the corresponding MQTT topic can be issued without a payload, the UART command can be issued without a value.
The following MQTT topic chart lists the corresponding UART command that would be used to accomplish the same action. The MQTT payload is the same as the UART value that would be used, unless otherwise noted.
General MQTT Topic Notes
There are two sets of MQTT topics. Once set is prefixed by the 'command' topic and the other is the prefixed by the 'state' topic. The default topic 'roots' for each of these are 'cmnd/deskamp' and 'stat/deskamp' unless you change these in the Settings.h file.
MQTT 'Command' Topics
These are the topics that the amp subscribes to, and are generally commands issued from an MQTT publisher to change some state of the amp. If a 'Y' appears in the Empty Payload column, the command can be issued without a payload to just force an update of the corresponding state (/stat) topic from the amp. Similary, the 'Update /stat' column indicates that the command also forces an MQTT /stat update from the amp (whether payload is supplied or not). Command topics should be issued with a retain flag of FALSE or ghosting may occur.
Topic 'root': cmnd/deskamp
| Topic | Payload | Empty Payload | Updates /stat | UART Cmd | Notes |
|---|---|---|---|---|---|
| /source | string | Y | Y | SRC | Set active source. Valid payloads: NET/USB/USBDAC/LINE-IN/BT/OPT/COAX/I2S/HDMI (any sources not supported by your amp will return an invalid command) |
| /system | string | N | N | SYS | Valid payloads: REBOOT/STANDBY/RESET/RECOVER Use with caution! |
| /wifireset | none | Y | N | WRS | Will reset wifi connection, requiring onboarding again Use with caution! |
| /volume | 0 to 100 | Y | Y | VOL | Set current volume level |
| /mute | 0 or 1 | Y | Y | MUT | Enable (1) or disable (0) mute |
| /bass | -10 to 10 | Y | Y | BAS | Sets the current bass level |
| /midrange | -10 to 10 | Y | Y | MID | Sets the current midrange level |
| /treble | -10 to 10 | Y | Y | TRE | Sets the current treble level |
| /led | 0, 1, T | Y | Y | LED | Disables (0), enables (1) or toggles (T) the onboard LED. Will also set the state of the extended LED if installed |
| /beep | 0 or 1 | Y | Y | BEP | Disables (0) or enables (1) the keypress beeps from the amp |
| /voice | 0 or 1 | Y | Y | PMT | Disables (0) or enables (1) amp voice prompts |
| /virtbass | 0, 1, T | Y | Y | VBS | Disables (0), enables (1) or toggles virtual bass |
| /pregain | 0 or 1 | Y | Y | PRG | Disables (0) or enables (1) pregain |
| /balance | -100 to 100 | Y | Y | BAL | Sets balance, -100 full left, 100 full right. O is midpoint |
| /maxvol | 30 - 100 | Y | Y | MXV | Set the max volume permitted. Used to limit volume adjustment |
| /irmode | 0 or 1 | N | Y | --- | Disables (0) or enables (1) custom IR receiver. Does not affect onboard IR receiver |
| /poweronsource | string | Y | Y | POM | Sets the default power on source. See /source for valid payloads. Use NONE to power on to last source used |
| /bluetooth | 0 or 1 | Y | Y | BTC | Disable or enable bluetooth, or disconnect/reconnect last device |
| /loopmode | string | N | Y | LPM | Sets loop playback mode. Value payloads are REPEATALL/REPEATONE/REPEATSHUFFLE/SHUFFLE/SEQUENCE |
| /preset | 0 - 10 | Y | Y | PST | Gets the specified preset (presets have to defined via mobile app) |
| /delay | 1 - 60 | Y | Y | DLY | Sets delay when audio is disabled after no signal, in seconds |
| /autoswitch | 0 or 1 | Y | Y | ASW | Disables/enables auto-switch to previous source after playback stops |
| /syncvol | 0 or 1 | Y | Y | VOS | Disables/enables volume sync between devices when in multi-room mode |
| /uart | string | N | Y | --- | Send raw UART command directly to amp. Must be formatted properly (see above) |
These commands only work with certain sources, primarily USB
| Topic | Payload | Empty Payload | Updates /stat | UART Cmd | Notes |
|---|---|---|---|---|---|
| /pause | none | Y | N | POP | Toggles the pause/play state. Will pause if playing or play if paused. Interchangable with /play |
| /play | none | Y | N | POP | Toggles the pause/play state. Identical and interchangeable with /pause |
| /stop | none | Y | N | STP | Stops current playback |
| /next | none | Y | N | NXT | Moves to the next track. Does not work with some sources |
| /previous | none | Y | N | PRE | Moves to the previous track. Does not work with some sources |
These commands only force an immediate update of related state (/stat) topic Payloads, if specified, are ignored. See state topics below for details on payloads returned.
| Topic | Payload | Empty Payload | Updates /stat | UART Cmd | Notes |
|---|---|---|---|---|---|
| /status | none | Y | Y | STA | This updates the following state topics: source, volume, mute, treble, base, network, internet, playing and led. |
| /devicename | none | Y | Y | NAM | Updates the device name state topic |
| /version | none | Y | Y | VER | Updates the firmware version state topic |
| /internet | none | Y | Y | WWW | Updates the internet state topic |
| /ethernet | none | Y | Y | ETH | Updates the ethernet state topic |
| /wifi | none | Y | Y | WIF | Updates the wifi state topic |
| /channel | none | Y | Y | CHN | Updates the channel state topic |
| /multiroom | none | Y | Y | MRM | Updates the multiroom state topic |
| /playing | none | Y | Y | PLA | Updates the playing state topic |
| /audio | none | Y | Y | AUD | Update the audio state topic |
| /fixedvol | none | Y | Y | VOF | Updates the fixed volume state topic |
| /tracknum | none | Y | Y | PLI | Updates the current track num state topic |
| /elapsed | none | Y | Y | ELP | Update the track elapsed time state topic |
MQTT 'State' Topics
These are the topics that the amp pubishes to, and are used to report various states of the amp. A state is generally updated any time it changes, but an update can be forced by issuing the corresponding /cmnd topic (see above for list). If a topic is published TO the amp with any of these topics, with or without payload, it is simply ignored. The amp will only accept topics from the /cmnd list. The payload column shows values returned from the amp for the corresponding topics. All /stat topics are published with a retain flag of TRUE.
Topic 'root': stat/deskamp
| Topic | Payload | UART | Notes |
|---|---|---|---|
| /devicename | string | NAM | Device name as specified during setup. Case-sensitive |
| /version | string | VER | Current amp/firmware version as firmware-build-api (ex. 36-30cb0ae0-6) |
| /interent | 0 / 1 | WWW | Connected (1) or not connected (0) to the Internet |
| /ethernet | 0 / 1 | ETH | Connected (1) or not connected (0) via Ethernet |
| /wifi | 0 / 1 | WIF | Connected (1) or not connected (0) via Wifi |
| /btconnect | 0 / 1 | BTC | Bluetooth enabled/connected (1) or disabled/disconnected (0) |
| /channel | string | CHN | Current channel config: Left, Right or Stereo |
| /multiroom | string | MRM | Multi-room state: Master, Slave or None |
| /source | string | SRC | Current source (in caps): NET/USB/USBDAC/LINE-IN/LINE-IN2/BT/OPT/COAX/I2S/HDMI/INVALID |
| /volume | 0 - 100 | VOL | Current volume |
| /mute | 0 / 1 | MUT | Current mute state off (0) or on (1) |
| /bass | -10 - 10 | BAS | Current bass level from -10 to 10 |
| /midrange | -10 - 10 | MID | Current midrange level from -10 to 10 |
| /treble | -10 to 10 | TRE | Current treble level from -10 to 10 |
| /led | 0 / 1 | LED | LED indicator is disabled (0) or enabled (1) |
| /beep | 0 / 1 | BEP | Amp keypress beeps are disabled (0) or enabled (1) |
| /voice | 0 / 1 | PMT | Amp voice promts are disabled (0) or enabled (1) |
| virtbass | 0 / 1 | VBS | Virtual base disabled (0) or enabled (1) |
| /pregain | 0 / 1 | PRG | Pregain is disabled (0) or enabled (1) |
| /maxvol | 30 - 100 | MXV | Max volume allowed |
| /irmode | 0 / 1 | --- | Custom IR received disabled (0) or enabled (1). Does not apply to onboard IR receiver |
| /poweronsource | string | POM | Default source at power on, value from source or NONE if set to power on with same source at last power off |
| /audio | 0 / 1 | AUD | Audio output is disabled (0) or enabled (1). Will switch off when in standby or after no signal is received for the delay period specified by /delay above |
| /fixedvol | 0 / 1 | VOF | Fixed volume is disable (0) or enabled (1) |
| /ircode | integer | --- | Last IR code received via the custom IR receiver. Does not apply to onboard IR |
| /uart | string | --- | Last UART command received by the amp |
These topics are only applicable for certain sources and are only updated when a change occurs or a corresponding /cmnd topic is received
| Topic | Payload | UART | Notes |
|---|---|---|---|
| /loopmode | string | LMP | One of the following returned (all caps): REPEATALL/REPEATONE/REPEATSHUFFLE/SHUFFLE/SEQUENCE |
| /tracknum | string | PLI | Returns current track/total tracks (e.g. 3/10) |
| /elaspsed | string | ELP | Time elapses/total track time in milliseconds (e.g. 530/371000). Does not auto-update on a set interval from the amp. |
These topics are only applicable for certain sources and are ONLY updated when a change occurs (cannot be 'force udpated'via /cmnd command)
| Topic | Payload | UART | Notes |
|---|---|---|---|
| /playing | 0 / 1 | PLA | Indicates whether audio is playing (1) or not (0) |
| /title | string | TIT | Title of current song |
| /artist | string | ART | Artist of current song |
| /album | string | ALB | Album of current song |
Not all topics will work with all sources. For example, title, artist and album may not be available for bluetooth streaming. However, there may be alternatives for getting these values for some sources. For recommendations and examples of how to use these MQTT topics in Home Assistant (or other autoamtion platforms), see the Home Assistant integration wiki page and the /homeassistant folder of this repo.