Communication Protocol

Originally, we just needed to transmit the door open / closed status; that is, one bit of information. But pretty quickly one realizes that there is a need to pass on some timing information, some means to track message integrity, undelivered messages, etc. So, it ends up with some sort of a mini-protocol, defined in MailBoxMessage.h header.

Addressing

Each communication node (transmitter or receiver) is assigned an address Communication Channel.Receiver ID.Mailbox ID:

• Communication Channel (1–127) corresponds to AT+Cnnn setting of HC-12 (see its user manual);
• Receiver ID (1–15) identifies receiver working on a given channel. 0 means message addressed to any receiver listening;
• Mailbox ID (1–15) identifies mailbox reporting to a given receiver. 0 is reserved for the receiver itself.

Examples:

• 07.01.02 — mailbox #2 reporting to receiver #1 on communication channel #7 (435.8 MHz);
• 15.03.00 — receiver #3 working on communication channel #15.

Common Rules

All nodes who wish to communicate must use the same communication channel. Even though HC-12 allows for reconfiguration at run-time, it is not being used. All HC-12 are pre-programmed to a given channel (see Getting Started); the rest of the software makes no assumption on the channel being used.

Receiver must accept all messages carrying its ID, as well as messages with receiver ID 0; other messages must be discarded (but may be logged). Mailbox (transmitter) must identify itself with a non-zero ID.

Each message carries a version of a protocol and a checksum; messages with mismatch in protocol or checksum must be discarded (but may be logged). Protocol version 0 is reserved for development purposes; applications may accept it at their own risk. Systems in production must use a non-zero version of the protocol. Protocol version must be incremented every time an incompatible change is made. The current version of the protocol is 2.

Message Format

Each message consists of eight bytes, as follows:

Byte.Bit	Content
Header
0.0–3	Protocol version (0–15)
0.4–7	Receiver ID (0–15)
Mailbox Status
1.0–3	Mailbox ID (1–15)
1.4	Boot Status (0–wake up from deep sleep, 1–boot for other reason)
1.5	Online Status (0–offline (going to sleep), 1–online (staying awake))
1.6	Door Status (0–closed, 1–open)
1.7	(reserved)
Message Number
2–3	Through Message Number (1–65535)
Timestamp
4–5	Local Time (ms from boot) (0–65535)
Battery Status
6.0–6	Battery Level (0–100 %)
6.7	(reserved)
Checksum
7	Checksum