1. RTOS RS485 hotel edition integration protocol

AI voice panel / smart home panel —— third-party RS485 guest control device integration protocol

1.1. 1. Overview

  This document describes the serial port communication protocol between the AI voice screen (hereinafter the screen) and third-party RS485 guest control devices/RCUs (hereinafter the device).

• Physical interface: RS485, half duplex
• Baud rate: 9600 by default (can be changed in the configuration file, see 2.1), 8 data bits, no parity, 1 stop bit
• Frame length: fixed 8 bytes, sent continuously, no escaping

  Click to download the sample configuration file

1.1.1. 1.1 Transmission direction convention

1.1.2. 1.2 Common frame format

  For the specific meaning of the data bytes in each frame type, see chapters 3 and 4.

1.1.3. 1.3 Checksum algorithm

  The checksum is the last byte (byte 8) and is calculated over the first 7 bytes with the following C algorithm:

u8 CheckSumR(u8 *p, u8 len1)
{
    u16 sum16 = 0;
    u8 i = 0, Sum2 = 0;
    for (; i < len1 - 1; i++)
        sum16 += p[i];
    Sum2 = ((((sum16 * 8) / 7 + sum16 % 3 + sum16 % 2) + 1) & 0xff);
    Sum2 = (Sum2 / 2 + 2) & 0xff;
    return Sum2;
}

When calling it, len1 = 8; the checksum byte itself is not included in the accumulation. The checksum values of all example frames in this document have been calculated with this algorithm and can be used directly to verify that a program is correct.

  Frames with a wrong checksum and frames whose length is not 8 bytes are always discarded by the screen; the device side should perform the same check.

1.2. 2. Configuration file protocol

  The device mapping of the screen is described by a text configuration file, which is delivered to the screen by the back-end/AIS platform (it can also be updated through smart_bus.txt on an SD card). Device manufacturers must provide the configuration content in the format described in this chapter.

File format requirements:

• Use :: as the separator, one entry per line, carriage return + line feed
• Encoding UTF-8, without a BOM header (a BOM makes the first line fail to be recognized)
• Empty lines are not recognized; the software removes duplicates automatically when generating

1.2.1. 2.1 Configuration header (485 V1 protocol)

  The first line of the file contains the baud rate and the plug-in parameters, in the format:

#baud rate::plug-in flag::command interval(ms, optional)

Example:

#9600::1::100

1.2.2. 2.2 Device entries

Name::Type::ID::Circuit::State::Displayed

  Wake word entries (the type is 0x00; several can be configured):

Hello, Xiaofei::0x00::Hello, master

That is, wake word::0x00::wake-word response.

1.2.3. 2.3 Device type list

1.2.4. 2.4 Boot music configuration (new in V2)

boot_music::0x51::music file MD5::music file URL

Example:

boot_music::0x51::e828daa5939ca69d61fff20dd1556b99::http://qny.aispeaker.com/android/tmp/wang-qing-shui-short.mp3

• The URL points to an mp3 file; the MD5 is the digest of that file, used to verify the downloaded cache
• Once configured, the device sends a 0x51 event frame (see 4.5) when booting is complete and the serial port is ready, and the screen plays that music after receiving it

1.2.5. 2.5 TV channel table configuration (new in V2, used with the 0x52 TV)

channel:{"1":"CCTV-1", "23":"CCTV News", "6":"Movie Channel"}

• JSON format, must be written on a single line, with no line breaks: the key is the channel number (a decimal string), the value is the channel name
• Used to map a channel name spoken by voice (e.g. "I want to watch CCTV-1") to the channel number, which is then sent with the 0x52 set-channel command (3.6)

1.2.6. 2.6 SIP configuration (new in V2, hotel intercom)

SIPSERVER::username::password::SIP server::port number::protocol(TCP/UDP/TLS)::proxy server(optional)
SIPHOTEL::front desk number

Example:

SIPSERVER::8001::123456::sip.hotel.com::5060::UDP::proxy.hotel.com
SIPHOTEL::9001

• SIPSERVER: the SIP registration account information of the screen; once it is fully configured the screen registers automatically at boot
• SIPHOTEL: the front desk SIP account, used for hotel scenarios such as "call the front desk"
• The proxy server field can be omitted when there is no proxy
• This item is screen-side network configuration and does not use the 485 channel

1.2.7. 2.7 Complete configuration example

#9600::1::100
boot_music::0x51::e828daa5939ca69d61fff20dd1556b99::http://qny.aispeaker.com/android/tmp/wang-qing-shui-short.mp3
SIPSERVER::8001::123456::sip.hotel.com::5060::UDP
SIPHOTEL::9001
Hello, Xiaofei::0x00::Hello, master
Home::0x29::0x19::0x03::0x01::0x00
Away::0x29::0x19::0x04::0x01::0x00
Main light::0x30::0x19::0x08::0x01::0x00
Reading lamp::0x2B::0x0A::0x01::0x01::0x00
Mirror light::0x30::0x19::0x09::0x01::0x00
Curtain open::0x31::0x19::0x0D::0x01::0x00
Curtain close::0x31::0x19::0x0D::0x00::0x00
Curtain stop::0x31::0x19::0x0E::0x01::0x00
Master bedroom AC::0x2D::0x1A::0x01::0x01::0x00
TV::0x52::0x19::0x01::0x01::0x00
channel:{"1":"CCTV-1", "23":"CCTV News", "6":"Movie Channel"}
Dream curtain::0x50::0x19::0x01::0x01::0x00
Progress curtain::0x53::0x19::0x02::0x01::0x00

1.3. 3. Screen → device control commands (frame header 0x7F)

1.3.1. 3.1 Voice light switch / scene / relay curtain (types 0x30, 0x29, 0x31)

  Scenes (0x29) and relay curtains (0x31) are still sent with the type code 0x30; they are distinguished by the circuit in the configuration file.

• Button number: 1~24, corresponding to the circuits in the configuration
• Attribute 1: 0x01 high level / 0x00 low level (sent according to the state field in the configuration)
• Attribute 2:
  • 0xFF normal switch press
  • 0x01 turned on by voice (special cases such as curtains also send 0x01, because "close the curtain" also switches a relay on)
  • 0x00 turned off by voice
• Attribute 3: 0x30 indicates an AI switch

1.3.2. 3.2 Dimming switch (type 0x2B)

• Brightness value: 0x00~0x64 (0~100 percent); 0x64 is sent to turn on, 0x00 to turn off
• Attribute 2: 0x00 normal; 0x80 means that only the lights which are currently on are controlled
• The device only has to report the matching brightness value in its status, as described in 4.2

1.3.3. 3.3 Voice temperature control / floor heating (types 0x2D, 0x2E)

• Byte 3 is fixed to 0x80 (Bt7=1 indicates an AI panel); byte 6 is fixed to 0xCA, which makes it easy for the device to check the frame separately
• Key number (byte 4):

• Attribute 2 (byte 5):

1.3.4. 3.4 IR TV (type 0x3C, not a 485 device)

  Byte 3 is fixed to 0xFF (the IR type is not distinguished; the screen determines the TV type). Main key codes:

Code library (byte 5): the default 0x00 = standard code library; >=0x00 is the device code library number, e.g. 0x0C is a TCL TV, in which case the key code is a TCL key code directly.

For TVs controlled directly over 485, use the 0x52 type added in V2 (see 3.6).

1.3.5. 3.5 Dream curtain (type 0x50) [new in V2]

Configuration example:

Dream curtain::0x50::0x19::0x01::0x01::0x00

• Progress value: 0~100, 100 fully open, 0 fully closed (the voice command "open the dream curtain" sends 100, "close the dream curtain" sends 0, "open the dream curtain to 50%" sends 50)
• Angle value: the blade angle value of the dream curtain, passed through by the screen unchanged (the device interprets it with its own angle range)
• Pause flag: 1 pause the curtain, 0 not relevant (set to 1 only for the voice command "pause the curtain", otherwise 0)

Example —— set progress 48 (0x30) and angle 32 (0x20):

7F 50 19 30 20 00 00 34

Example —— pause:

7F 50 19 30 20 01 00 36

  The device should report its actual progress and angle as described in 4.4.

1.3.6. 3.6 RS485 TV (type 0x52) [new in V2]

Configuration example (for the channel table see 2.5):

TV::0x52::0x19::0x01::0x01::0x00
channel:{"1":"CCTV-1", "23":"CCTV News", "6":"Movie Channel"}

Command (byte 3) definitions:

Example frames (ready to verify):

This type has no status report frame: after sending a command the screen updates the UI state directly and the device does not have to respond (status synchronization can be added later as an extension if required).

1.3.7. 3.7 Progress curtain (type 0x53) [new in V2]

Configuration example:

Progress curtain::0x53::0x19::0x01::0x01::0x00

• Progress value: 0~100, 100 fully open, 0 fully closed
• Pause flag: 1 pause the curtain, 0 not relevant

Example frames:

  The device should report its actual progress as described in 4.6.

1.3.8. 3.8 Screen-ready notification and status query

1. Ready notification: after the screen finishes booting and the 485 serial port is ready, it proactively sends one ready notification frame, which the device may ignore:

   7F 01 01 01 01 01 01 4F
   

2. Status query: when the configuration is binding mode 1, after the screen starts (or refreshes the devices) it sends a query frame to every light switch (0x30), dimmer (0x2B) and temperature control (0x2D) device in the configuration one by one. Its distinguishing features are button number 0x00 and both attribute 1 and attribute 2 equal to 0x00; attribute 3 is 0xCA for temperature control and 0x30 for the others:

   | Query target | Query frame format (ID=0x19 example) | | ---- | ---- | | Light switch | 7F 30 19 00 00 00 30 11 | | Dimming switch | 7F 2B 19 00 00 00 30 0D | | Temperature control | 7F 2D 19 80 00 00 CA 31 |

   After receiving a query frame the device must report its current status immediately in the format of chapter 4 (the interval between queries is controlled by the configured command interval; the default is only 2 ms, so the response capability of the device must be taken into account).

3. Command interval: after sending each control command the screen waits for the configured interval (see 2.1) before sending the next one.

1.4. 4. Device → screen status reports (frame header 0x7E)

1.4.1. 4.1 Switch output status (type 0x02)

• Each AI switch ID supports up to 24 circuits; use several IDs when there are more
• Circuit code: set to 0x81 (Bit0=1 means the first group, Bit7=1 means the button backlight is on)

• Status 1~3: the bits correspond to the circuit states, bit0 is circuit 1, bit1 is circuit 2 ...; a bit set to 1 means on. For example, circuit 8 on:

  7E 02 19 81 80 00 00 6D
  

1.4.2. 4.2 Dimming output status (type 0x03)

• Each AI dimming switch ID supports up to 4 channels, brightness 0~100
• Example —— ID 0x0A dimming channel 1 set to 100%: 7E 03 0A 64 00 00 00 0C; set to 0%: 7E 03 0A 00 00 00 00 52

1.4.3. 4.3 AC / floor heating status (type 0x04)

• Temperature offset value: positive numbers 0~7, negative numbers 8~15
• Set temperature: 0~31 (°C)
• Indoor temperature: signed value, 0~60 means 0~60°C, negative temperatures are expressed in two's complement (e.g. 0xFE means -2°C)
• Status 1 is defined bit by bit:

• Example —— AC on, fan mode, low speed, set to 24°C, room temperature 25°C: 7E 04 1A 18 17 18 19 12
• Example —— floor heating on, set to 24°C, room temperature -2°C: 7E 04 1B 18 17 18 FE 16

1.4.4. 4.4 Dream curtain status report (type 0x50) [new in V2]

• The device reports its actual progress (0~100) and blade angle while an action is running and after it finishes
• Example —— progress 48, angle 32: 7E 50 19 30 20 00 00 35

1.4.5. 4.5 Boot music trigger (type 0x51) [new in V2]

• After the device finishes booting and the serial port is ready, it sends this frame to notify the screen; on receipt the screen plays the boot music configured in 2.4 and applies the hotel mode volume
• Play flag: 1 play, 0 do not play

• The standard frame is fixed as:

  7E 51 00 00 01 00 00 79
  

1.4.6. 4.6 Progress curtain status report (type 0x53) [new in V2]

• Example —— progress 48: 7E 53 19 30 00 00 00 23

1.4.7. 4.7 Binding / refresh (type 0xFF)

When the plug-in flag is enabled (flag=1 in 2.1), the device must report its binding status within 3 seconds after RESET, otherwise the screen treats the device as not bound:

Corresponding commands on the screen side:

1.5. 5. Local relay control (optional, module solution)

  The screen itself has two local relay channels (when the RS485 plug-in occupies the 485 port, the device side can control the screen relays in the reverse direction):

Device → screen, control the relays:

Screen → device, report the relay status:

1.6. 6. Appendix

1.6.1. 6.1 Integration checklist

1. The baud rate, plug-in flag and command interval match the configuration header
2. All frames are exactly 8 bytes, the checksum follows the algorithm in 1.3, and both sides discard frames with a failed checksum or a wrong length
3. In binding mode (flag=1) the device reports the binding status frame within 3 seconds after RESET
4. When the screen powers on it sends query frames one by one (button number=0x00); the device must answer with its current status correctly
5. Notes on the new devices:
   • Dream curtain (0x50): receive control per 3.5, report progress + angle per 4.4
   • Progress curtain (0x53): receive control per 3.7, report progress per 4.6
   • RS485 TV (0x52): receive the 8 commands per 3.6, no status report needed. Older TVs do not support voice control of channels and similar functions, so this type is the preferred choice for TV integration
   • Boot music (0x51): once the device is ready it sends the trigger frame per 4.5
6. The channel table channel: must be a single line of JSON; the configuration file is UTF-8 without BOM, uses :: as the separator and has one entry per line

1.6.2. 6.2 Debugging and factory test

• Screen-side factory test entry: after booting, pull down at the top of the main page and go to Settings → Advanced settings → tap the upper-right corner 5 times or more to enter the factory test page; the module&485 test item shows OK when serial communication works properly (OK is shown as soon as the serial port has ever received a binding/unbinding frame)
• Configuration update: when the size of smart_bus.txt on the SD card differs from /data/jdsmart_open/smart_bus.txt on the screen, it is overwritten automatically
• The device side can trigger the screen to re-fetch the device configuration by sending 7E FF 01 02 00 00 00 5D

1.6.3. 6.3 Voice commands and device names

• Voice control uses the name from the configuration directly, so names should follow the habits of guests (e.g. "Main light", "Mirror light", "Curtain open")
• Curtain types (0x31) are aggregated by name suffix: the three lines open/close/stop of the same device name are merged into a single curtain device