ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
apc_proteous_cover.cpp
Go to the documentation of this file.
2#include "esphome/core/log.h"
4
6
7ESPHOME_LOG_TAG(TAG, "apc_proteous.cover");
8static constexpr const char *START_CMD = "*1\r"; // start/stop toggle
9static constexpr const char *OPEN_CMD = "*6\r";
10static constexpr const char *CLOSE_CMD = "*7\r";
11static constexpr const char *QUERY_S = "?s\r";
12static constexpr const char *QUERY_X = "?x\r";
13
14// Depending on calibration the reported position may stop a little short of the physical limits
15// (e.g. 99% at the fully open reed switch), so readings this close to an end count as that end.
16static constexpr uint8_t ENDPOINT_MARGIN = 2;
17
18using namespace esphome::cover;
19
21 auto restore = this->restore_state_();
22 if (restore.has_value()) {
23 restore->apply(this);
24 } else {
25 this->position = 0.5f;
26 }
27}
28
30 this->read_available([this](uint8_t data) {
31 const char *line = this->line_reader_.feed(data);
32 if (this->line_reader_.overflowed()) {
33 // Start over from this byte, so a frame right after unterminated noise is still read
34 ESP_LOGVV(TAG, "rx overflow, discarding");
35 this->line_reader_.restart_with(data);
36 } else if (line != nullptr && line[0] != '\0') {
37 ESP_LOGVV(TAG, "rx: '%s'", line);
38 this->parse_response_(line);
39 }
40 });
41}
42
43void APCProteousCover::parse_response_(const char *line) {
44 // Expected format: "?s=XX" or "?x=XX" where XX is a hex value
45 if (line[0] != '?' || line[1] == '\0' || line[2] != '=' || line[3] == '\0') {
46 ESP_LOGV(TAG, "Invalid response: %s", line);
47 return;
48 }
49
50 const char *hex_str = line + 3;
51 char *end_ptr;
52 uint8_t value = static_cast<uint8_t>(strtol(hex_str, &end_ptr, 16));
53 if (end_ptr == hex_str) {
54 ESP_LOGW(TAG, "Failed to parse hex value: %s", line);
55 return;
56 }
57
58 bool state_changed = false;
59 char type = line[1];
60 if (type == 's') {
61 // bit 0 = operating, bit 1 = direction (0 = opening, 1 = closing)
63 if (value & 0x01) {
64 new_operation = (value & 0x02) ? COVER_OPERATION_CLOSING : COVER_OPERATION_OPENING;
65 }
66 if (this->current_operation != new_operation) {
67 this->current_operation = new_operation;
68 state_changed = true;
69 }
70 // Motion in the commanded direction acknowledges the pending command
71 if ((this->pending_command_ == OPEN_CMD && new_operation == COVER_OPERATION_OPENING) ||
72 (this->pending_command_ == CLOSE_CMD && new_operation == COVER_OPERATION_CLOSING)) {
73 this->clear_pending_();
74 }
75 // A partial move is over once the acknowledged motion has stopped, wherever it stopped, so an
76 // old target cannot halt a movement started from the wall button or the remote later on
77 if (new_operation == COVER_OPERATION_IDLE && this->pending_command_ == nullptr) {
78 this->target_position_.reset();
79 }
80 ESP_LOGV(TAG, "s-status: 0x%02X (operation=%d)", value, new_operation);
81 } else if (type == 'x') {
82 // Position percentage, snapped to the ends so is_open/is_closed can latch despite calibration offsets
83 float new_position;
84 if (value + ENDPOINT_MARGIN >= 100) {
85 new_position = COVER_OPEN;
86 } else if (value <= ENDPOINT_MARGIN) {
87 new_position = COVER_CLOSED;
88 } else {
89 new_position = value / 100.0f;
90 }
91 if (this->position != new_position) {
92 this->position = new_position;
93 state_changed = true;
94 // Until the controller has confirmed motion in the commanded direction, current_operation may
95 // still show the previous one, so a reversing partial move must not be judged against it
96 if (this->target_position_.has_value() && this->pending_command_ == nullptr &&
97 ((this->current_operation == COVER_OPERATION_OPENING && this->position >= *this->target_position_) ||
98 (this->current_operation == COVER_OPERATION_CLOSING && this->position <= *this->target_position_))) {
99 ESP_LOGD(TAG, "Target position %.2f reached", *this->target_position_);
101 }
102 }
103 ESP_LOGV(TAG, "x-status: %d%% (position=%.2f)", value, this->position);
104 }
105
106 if (state_changed) {
107 this->publish_state();
108 }
109}
110
112 this->pending_command_ = nullptr;
113 this->command_retries_ = 0;
114}
115
117 if (this->pending_command_ == nullptr || (now - this->pending_command_time_) < COMMAND_ACK_MS) {
118 return;
119 }
120 bool is_open_cmd = this->pending_command_ == OPEN_CMD;
121 // Nothing to resend once the gate is at the commanded end
122 if ((is_open_cmd && this->position >= COVER_OPEN) || (!is_open_cmd && this->position <= COVER_CLOSED)) {
123 this->clear_pending_();
124 return;
125 }
126 const LogString *label = is_open_cmd ? LOG_STR("open") : LOG_STR("close");
128 ESP_LOGW(TAG, "Gate did not acknowledge %s command after %u retries", LOG_STR_ARG(label), this->command_retries_);
129 this->clear_pending_();
130 this->target_position_.reset();
131 return;
132 }
133 this->command_retries_++;
134 ESP_LOGD(TAG, "Gate did not respond, resending %s command (retry %u)", LOG_STR_ARG(label), this->command_retries_);
135 this->pending_command_time_ = now;
136 this->write_command_(this->pending_command_, now);
137}
138
141 this->retry_pending_command_(now);
142
143 // Let the command and its echo clear the line before the next query
144 if ((now - this->last_command_tx_) < COMMAND_QUIET_MS) {
145 return;
146 }
147 // The line is idle, so anything left in the buffer is an unterminated echo
148 if (this->line_reader_.length() != 0) {
149 ESP_LOGVV(TAG, "discarding stale rx '%s' before query", this->line_reader_.partial());
150 }
151 this->line_reader_.reset();
152
153 const char *query = this->query_s_next_ ? QUERY_S : QUERY_X;
154 ESP_LOGVV(TAG, "tx: %s", query);
155 this->write_str(query);
156 this->query_s_next_ = !this->query_s_next_;
157}
158
160 LOG_COVER("", "APC Proteous Cover", this);
161 LOG_UPDATE_INTERVAL(this);
162}
163
165 auto traits = CoverTraits();
166 traits.set_supports_position(true);
167 traits.set_supports_stop(true);
168 traits.set_supports_toggle(true);
169 return traits;
170}
171
172void APCProteousCover::write_command_(const char *cmd, uint32_t now) {
173 ESP_LOGVV(TAG, "tx: %s", cmd);
174 this->last_command_tx_ = now;
175 this->write_str(cmd);
176}
177
178void APCProteousCover::send_command_(const char *cmd) {
179 // The published state comes only from status reads; this just records the command so a stop
180 // can cancel it before the controller reports motion, and so it can be resent if dropped.
181 // The commands are idempotent, so only skip one when the gate is already moving that way.
182 CoverOperation operation = cmd == OPEN_CMD ? COVER_OPERATION_OPENING : COVER_OPERATION_CLOSING;
183 if (this->current_operation == operation) {
184 return;
185 }
186 ESP_LOGD(TAG, "Sending %s command",
187 operation == COVER_OPERATION_OPENING ? LOG_STR_LITERAL("open") : LOG_STR_LITERAL("close"));
189 this->pending_command_ = cmd;
190 this->pending_command_time_ = now;
191 this->command_retries_ = 0;
192 this->write_command_(cmd, now);
193}
194
196 // START_CMD is a start/stop toggle, so it is only sent while the gate is moving, or while a
197 // movement command is in flight that the controller has not reported yet; otherwise it would start the gate.
198 if (this->current_operation == COVER_OPERATION_IDLE && this->pending_command_ == nullptr) {
199 ESP_LOGD(TAG, "Cover already idle, ignoring stop command");
200 return;
201 }
202 ESP_LOGD(TAG, "Sending stop command");
203 this->write_command_(START_CMD, now);
204 this->clear_pending_();
205 this->target_position_.reset();
206}
207
209 if (call.get_stop()) {
211 } else if (call.get_position().has_value()) {
212 float target = *call.get_position();
213 ESP_LOGD(TAG, "Target position: %.2f, current: %.2f", target, this->position);
214 // There is no position command: a partial target is reached by moving towards it and stopping
215 // once the reported position gets there
216 this->target_position_.reset();
217 if (target == COVER_OPEN) {
218 this->send_command_(OPEN_CMD);
219 } else if (target == COVER_CLOSED) {
220 this->send_command_(CLOSE_CMD);
221 } else if (target != this->position) {
222 this->target_position_ = target;
223 this->send_command_(target > this->position ? OPEN_CMD : CLOSE_CMD);
224 }
225 } else if (call.get_toggle()) {
226 this->clear_pending_();
227 this->target_position_.reset();
229 }
230}
231
232} // namespace esphome::apc_proteous
uint32_t IRAM_ATTR HOT get_loop_component_start_time() const
Get the cached time in milliseconds from when the current component started its loop execution.
const char * partial()
The partial line, NUL terminated, for prompts with no line end; the first N - 1 characters on the byt...
Definition line_reader.h:60
bool overflowed() const
True only right after the feed() that found the line too long; the rest of that line is then dropped.
Definition line_reader.h:66
size_t length() const
Length of the partial line; 0 after a line is returned and while an overlong line is dropped.
Definition line_reader.h:56
char * feed(uint8_t c)
Feed one byte; returns the completed line (empty lines included), valid until the next call,...
Definition line_reader.h:23
void reset()
Forget the partial line and start a new one with the next byte.
Definition line_reader.h:76
void restart_with(uint8_t c)
Start a new line with c, e.g. the byte that overflowed; c must not be TERMINATOR_CHAR or IGNORE_CHAR.
Definition line_reader.h:79
LineReader< MAX_RESPONSE_LEN+1, '\r', '\n'> line_reader_
void control(const cover::CoverCall &call) override
void write_command_(const char *cmd, uint32_t now)
const optional< float > & get_position() const
Definition cover.cpp:99
CoverOperation current_operation
The current operation of the cover (idle, opening, closing).
Definition cover.h:120
optional< CoverRestoreState > restore_state_()
Definition cover.cpp:195
void publish_state(bool save=true)
Publish the current state of the cover.
Definition cover.cpp:158
float position
The position of the cover from 0.0 (fully closed) to 1.0 (fully open).
Definition cover.h:126
void write_str(const char *str)
Definition uart.h:37
bool read_available(F &&on_byte)
Same as read_available_chunks(), calling on_byte(uint8_t) once per byte.
Definition uart.h:77
uint8_t type
ESPHOME_LOG_TAG(TAG, "apc_proteous.cover")
CoverOperation
Enum encoding the current operation of a cover.
Definition cover.h:84
@ COVER_OPERATION_OPENING
The cover is currently opening.
Definition cover.h:88
@ COVER_OPERATION_CLOSING
The cover is currently closing.
Definition cover.h:90
@ COVER_OPERATION_IDLE
The cover is currently idle (not moving)
Definition cover.h:86
uint32_t value
Definition hal.cpp:41
Application App
Global storage of Application pointer - only one Application can exist.
static void uint32_t