ESPHome 2026.12.0-dev
Loading...
Searching...
No Matches
cardin_s438_protocol.cpp
Go to the documentation of this file.
2#include "esphome/core/hal.h"
4#include "esphome/core/log.h"
5
6namespace esphome::remote_base {
7
8ESPHOME_LOG_TAG(TAG, "remote.cardin_s438");
9
10namespace {
11
12/*
13 * Cardin S438 wire format
14 *
15 * Frame: 6400 us sync mark + 40 data bits (5 bytes, LSB-first).
16 * 0 = 1460 us space, 750 us mark
17 * 1 = 750 us space, 1460 us mark
18 *
19 * Bytes:
20 * [0..2] Encoded pin fields and seed
21 * [2] (seed + marker 0x87), modulo 256
22 * Carries propagate into bytes 1 and 0.
23 * [3..4] Sum of bytes [0..2], little-endian
24 *
25 * Pin code: 14 bits, MSB-first, mapped to X/Y fields:
26 * Y7,Y6,X7,X6,Y5,X5,Y4,X4,Y3,X3,Y2,Y1,Y0,X2
27 * Channels in X bits 1:0: A=10, B=00, C=11, D=01.
28 *
29 * Three frames per transmission, with 63650 us LOW gaps.
30 * Seed chosen randomly; no pattern found in captures.
31 */
32
33// Frame format and timing, in microseconds.
34constexpr uint8_t MARKER = 0x87;
35constexpr uint16_t SYNC_MARK_US = 6400;
36constexpr uint32_t FRAME_GAP_US = 63650;
37constexpr uint8_t WIRE_SIZE = 5;
38// Each bit is a space then a mark, and both lengths carry it
39constexpr BitTimings CARDIN_TIMINGS{
40 .one_space = 750, .zero_space = 1460, .one_mark = 1460, .zero_mark = 750, .space_first = true};
41
42// Maps pincode bits, most-significant first, to a bit of the X or Y field: PIN_Y marks Y, the low bits are the bit
43// number. In flash, so it stays out of RAM on ESP8266.
44constexpr uint8_t PIN_Y = 0x08;
45constexpr uint8_t PINCODE_BITS = 14;
46constexpr uint8_t PINCODE_MAP[PINCODE_BITS] PROGMEM = {
47 PIN_Y | 7, PIN_Y | 6, 7, 6, PIN_Y | 5, 5, PIN_Y | 4, 4, PIN_Y | 3, 3, PIN_Y | 2, PIN_Y | 1, PIN_Y | 0, 2,
48};
49
50// Convert the pincode and channel to the two decoded pin fields.
51void encode_pin_fields(uint16_t pincode, uint8_t channel, uint8_t &plain0, uint8_t &plain1) {
52 uint8_t x = channel;
53 uint8_t y = 0;
54
55 for (uint8_t i = 0; i < PINCODE_BITS; ++i) {
56 if (((pincode >> (PINCODE_BITS - 1 - i)) & 1U) == 0)
57 continue;
58 const uint8_t entry = progmem_read_byte(&PINCODE_MAP[i]);
59 (entry & PIN_Y ? y : x) |= 1U << (entry & 0x07);
60 }
61
62 plain1 = ~y;
63 plain0 = plain1 - x + 1;
64}
65
66// Construct the wire bytes for one seed.
67void build_wire(uint8_t wire[WIRE_SIZE], uint8_t seed, uint8_t plain0, uint8_t plain1) {
68 uint16_t sum = MARKER + seed;
69 wire[2] = sum;
70
71 uint8_t key = seed + (sum >> 8);
72
73 sum = plain1 + key;
74 wire[1] = sum;
75 key += sum >> 8;
76
77 wire[0] = plain0 + key;
78
79 // checksum over the first three bytes
80 put_le16(wire + 3, sum16_bytes(wire, 3));
81}
82
83} // namespace
84
86 uint8_t plain0;
87 uint8_t plain1;
88
89 encode_pin_fields(data.code & 0x3FFF, data.channel & 0x03, plain0, plain1);
90
91 for (uint8_t frame = 0; frame < data.repeats; ++frame) {
92 uint8_t wire[WIRE_SIZE];
93 uint8_t seed = static_cast<uint8_t>(random_uint32() & 0xFF);
94
95 build_wire(wire, seed, plain0, plain1);
96 dst->mark(SYNC_MARK_US);
97 dst->item_bytes<CARDIN_TIMINGS>(wire, WIRE_SIZE);
98 dst->space(FRAME_GAP_US);
99 }
100}
101
103 const TimingRange sync = src.timing_range(SYNC_MARK_US);
104 while (src.is_valid()) {
105 // Find the frame's long sync mark.
106 const bool found = sync.matches_mark(src.peek());
107 src.advance();
108 if (!found)
109 continue;
110
111 uint8_t wire[WIRE_SIZE];
112 if (!src.expect_bytes<CARDIN_TIMINGS>(wire, WIRE_SIZE) ||
113 encode_value_le<uint16_t>(wire + 3) != sum16_bytes(wire, 3)) {
114 continue;
115 }
116
117 // Recover the seed and undo the encoder's carry transform.
118 uint8_t seed = wire[2] - MARKER;
119
120 uint8_t key = seed;
121 key += (seed + MARKER) >> 8;
122
123 uint8_t plain1 = wire[1] - key;
124 key += (plain1 + key) >> 8;
125
126 uint8_t plain0 = wire[0] - key;
127
128 // Recover the original X and Y fields.
129 uint8_t x = plain1 - plain0 + 1;
130 uint8_t y = ~plain1;
131
132 // Reconstruct the 14-bit code in transmission order.
133 uint16_t code = 0;
134 for (const uint8_t &slot : PINCODE_MAP) {
135 const uint8_t entry = progmem_read_byte(&slot);
136 code = (code << 1) | (((entry & PIN_Y ? y : x) >> (entry & 0x07)) & 1U);
137 }
138
139 return CardinS438Data{
140 .code = code,
141 .channel = static_cast<uint8_t>(x & 0x03),
142 .seed = seed,
143 };
144 }
145
146 return {};
147}
148
150 // The DIP switches as the config takes them; channels as CARDIN_S438_CHANNELS in __init__.py maps them
151 char code[PINCODE_BITS + 1];
152 for (uint8_t i = 0; i < PINCODE_BITS; ++i)
153 code[i] = (data.code >> (PINCODE_BITS - 1 - i)) & 1U ? '1' : '0';
154 code[PINCODE_BITS] = '\0';
155 ESP_LOGI(TAG, "Received Cardin S438: code=%s channel=%c seed=0x%02X", code, "BDAC"[data.channel & 0x03], data.seed);
156}
157
158} // namespace esphome::remote_base
optional< CardinS438Data > decode(RemoteReceiveData src)
void encode(RemoteTransmitData *dst, const CardinS438Data &data)
void item_bytes(const uint8_t *bytes, size_t len)
One item per bit of each byte.
Definition remote_base.h:72
const char * key
ESPHOME_LOG_TAG(TAG, "remote.abbwelcome")
constexpr T encode_value_le(const uint8_t *bytes)
Encode a value from its constituent bytes (from least to most significant) in an array with length si...
Definition helpers.h:1210
uint32_t random_uint32()
Return a random 32-bit unsigned integer.
Definition helpers.cpp:10
const void * src
Definition hal.h:68
constexpr uint16_t sum16_bytes(const uint8_t *data, size_t len, uint16_t sum=0)
Add up the bytes of data with size len, truncated to 16 bits.
Definition helpers.h:1049
constexpr uint8_t * put_le16(uint8_t *dst, uint16_t value)
Definition helpers.h:1256
uint8_t progmem_read_byte(const uint8_t *addr)
Definition hal.h:51
static void uint32_t
A bit is a mark (one_mark or zero_mark, both bit_mark unless set) and a space (one_space or zero_spac...
Definition remote_base.h:52
The lengths that match one timing within the tolerance.
uint16_t sync
Definition sun_gtil2.cpp:0
uint16_t x
Definition tt21100.cpp:5
uint16_t y
Definition tt21100.cpp:6