ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
hoermann_hcp.h
Go to the documentation of this file.
1#pragma once
2
3#include <utility>
4
9#ifdef USE_BINARY_SENSOR
11#endif
12#ifdef USE_HOERMANN_HCP_IDENTITY
14#endif
15
16namespace esphome::hoermann_hcp {
17
18// Door state as reported by the Hoermann bus controller.
19enum class DoorState : uint8_t {
20 OPEN,
21 OPENING,
22 CLOSED,
23 CLOSING,
26 VENT,
28 STOPPED,
29};
30
31#ifdef USE_HOERMANN_HCP_IDENTITY
32// Payload registers of each value, two bytes each.
33static constexpr size_t SERIAL_FIRST_HALF_REGS = 7;
34static constexpr size_t SERIAL_SECOND_HALF_REGS = 6;
35static constexpr size_t FIRMWARE_REGS = 6;
36// Counter of the transfer the read half of the frame acknowledges. Real counters have the 0x80 half marker
37// stripped, so this value never occurs.
38static constexpr uint8_t NO_TRANSFER_ANSWER = 0xFF;
39
40// Where the identity exchange stands. The low nibble is the code the motor is asked with, 0 while nothing is
41// outstanding. Like Hoermann's own bus accessory, the first status answer stays ordinary. Older motors (index B1
42// seen) send the whole serial number in one frame, without the half marker.
43enum class IdentityPhase : uint8_t {
46 IDENTITY_PHASE_SERIAL = 0x05, // A plain frame is the whole serial number.
47 IDENTITY_PHASE_SERIAL_SPLIT = 0x15, // A half marker was seen, so a plain frame can only be the second half.
48 IDENTITY_PHASE_SERIAL_SECOND_HALF = 0x25, // The first half is in.
50};
51#endif
52
53// Sent once, in a single status answer, as Hoermann's own bus accessory does.
55 const char *name;
56 uint16_t value;
57 uint16_t value_2{0x0000};
58};
59
61#ifdef USE_BINARY_SENSOR
62 SUB_BINARY_SENSOR(actuator_error)
63#endif
64#ifdef USE_HOERMANN_HCP_IDENTITY
65 // The motor is asked for these only when one of them is configured.
66 SUB_TEXT_SENSOR(serial_number)
67 SUB_TEXT_SENSOR(version)
68#endif
69
70 public:
71 void update() override;
72 void dump_config() override;
73
74 // Registered by child entities to be notified when the door state changes.
75 template<typename F> void add_on_state_callback(F &&callback) {
76 this->state_callback_.add(std::forward<F>(callback));
77 }
78
79 // Modbus server callbacks. The bus controller pushes commands and polls state with 0x17 (the hub runs the write
80 // half first, storing the command register that the read half echoes back) and broadcasts status with 0x10.
81 modbus::ResponseStatus on_write_registers(uint16_t start_address, const modbus::RegisterValues &registers) override;
82 modbus::ResponseStatus on_read_holding_registers(uint16_t start_address, uint16_t number_of_registers,
83 modbus::RegisterValues &registers) override;
84
85 // Positions follow the cover convention: 0.0 is fully closed, 1.0 fully open. These return false when the bus
86 // controller cannot be asked right now, so the caller can react.
87 bool open_door();
88 bool close_door();
89 bool impulse_door();
90 // The door drives to these intermediate positions on its own, so neither takes a target to be stopped at.
91 bool vent_door();
92 bool half_open_door();
93 bool stop_door();
94 bool set_position(float position);
95 // False while the door has not reported the lamp.
96 bool set_light(bool on);
97
98 DoorState get_door_state() const { return this->door_state_; }
99 // False until a broadcast has carried a state the door is known to report. Bus traffic alone makes the
100 // connection valid, so get_door_state() would still be its default.
101 bool is_door_state_known() const { return this->door_state_seen_; }
102 float get_current_position() const { return this->current_position_; }
103 bool is_valid() const { return this->valid_; }
104 bool is_light_on() const { return this->light_on_; }
105 // False until a broadcast has actually carried the lamp register. Bus traffic alone makes the connection
106 // valid without saying anything about the lamp, so is_light_on() would still be its default.
107 bool is_light_known() const { return this->light_seen_; }
108 // The requested state while switching, else the reported one.
109 bool is_light_heading_on() const { return this->light_requested_ ? this->light_target_ : this->light_on_; }
110
111 protected:
112 void record_response_();
113 bool command_door_(const HoermannHcpCommand &command);
114 // Returns false when the bus controller has not fetched the previous command yet.
115 bool queue_command_(const HoermannHcpCommand &command);
116 void drop_command_();
119 // Decide at the fetch what goes into a status answer, against the door as it stands then.
122 void on_position_reg_(uint16_t value);
123 void on_state_reg_(uint16_t value);
124 void on_light_reg_(uint16_t value);
125#ifdef USE_HOERMANN_HCP_IDENTITY
126 // Puts a due request into a status answer.
127 void add_identity_request_(modbus::RegisterValues &registers, uint16_t command);
129 uint8_t identity_request_() const { return static_cast<uint8_t>(this->identity_phase_) & 0x0F; }
130 // True when the request is due, counting the attempt. Gives up after the last one.
132 // Takes a value the motor hands over as a payload transfer. Returns the counter to acknowledge it with, kept or
133 // not, or NO_TRANSFER_ANSWER when the frame was something else.
134 uint8_t take_identity_transfer_(const modbus::RegisterValues &registers);
135 // Acknowledges the transfer taken by the write half of the same frame.
136 void push_transfer_answer_(modbus::RegisterValues &registers, uint16_t number_of_registers);
137 // Runs from update(), outside the bus callbacks.
138 void publish_identity_();
139#endif
140
141 void set_valid_(bool valid);
143 // Recomputes the reported position from position_raw_ and the current door state.
145 bool has_target_() const { return this->target_position_ != 0.0f; }
146 bool is_moving_or_starting_() const;
147 void clear_target_();
148 void set_light_on_(bool on);
149 void set_light_seen_(bool seen);
150
152
153 float current_position_{0.0f};
154 // Position the door was told to travel to; 0.0 means no target is armed.
155 float target_position_{0.0f};
156
160 // Separate from command_queued_at_ so an unrelated command cannot extend the target's start deadline.
163 // Start of the wait for the fetch, then for the report.
167 bool stop_sent_{false};
168 // A door command was fetched and the door has not answered it by moving or reaching its destination yet.
169 bool starting_{false};
170
171 // Drop the "connected" flag if the bus controller has not polled us for this long.
173 // A chosen margin for a door to report moving after a fetched command.
174 uint16_t start_window_ms_{5000};
175 // The state starts on a value the bus controller never reports, so the first broadcast is decoded even when
176 // it reads 0x0000.
177 uint16_t prev_state_reg_{0xFFFF};
178 // 0x17 write half: command register last written to COMMAND_REG. The read half echoes its high-byte message
179 // counter and low-byte command back from STATE_REG.
181
183 // Direction the door was started in for the current target, judged only once the door reports moving that way.
185 // Position as reported by the bus controller, 0..200 across the full travel.
186 uint8_t position_raw_{0};
187 bool target_started_{false};
188 bool valid_{false};
189 bool changed_{false};
190 bool light_on_{false};
191 bool light_seen_{false};
192 bool light_requested_{false};
194 bool light_target_{false};
195 // Last reported, kept across a quiet bus so a reconnect logs only a real change.
196 bool actuator_error_{false};
197 bool door_state_seen_{false};
199 // Only the read half right after a 0x17 write carries a command, so a second read without a new write does not.
201
202#ifdef USE_HOERMANN_HCP_IDENTITY
206 // The request given up on, for update() to report.
208 uint8_t transfer_answer_counter_{NO_TRANSFER_ANSWER};
209 // Length of an unreadable firmware version left in firmware_version_.
211 // A serial number arrived without text, for update() to log.
214 char serial_number_[2 * (SERIAL_FIRST_HALF_REGS + SERIAL_SECOND_HALF_REGS) + 1]{};
215 char firmware_version_[2 * FIRMWARE_REGS + 1]{};
216#endif
217};
218
219} // namespace esphome::hoermann_hcp
This class simplifies creating components that periodically check a state.
Definition component.h:532
virtual void update()=0
Minimal static vector - saves memory by avoiding std::vector overhead.
Definition helpers.h:304
bool command_door_(const HoermannHcpCommand &command)
void set_door_state_(DoorState state)
uint8_t take_identity_transfer_(const modbus::RegisterValues &registers)
CallbackManager< void()> state_callback_
const HoermannHcpCommand * take_command_()
void arm_identity_request_(IdentityPhase phase)
const HoermannHcpCommand * next_command_
void push_command_registers_(modbus::RegisterValues &registers)
void add_identity_request_(modbus::RegisterValues &registers, uint16_t command)
const HoermannHcpCommand * start_command_
char firmware_version_[2 *FIRMWARE_REGS+1]
void push_transfer_answer_(modbus::RegisterValues &registers, uint16_t number_of_registers)
const HoermannHcpCommand * take_light_command_()
bool queue_command_(const HoermannHcpCommand &command)
void on_position_reg_(uint16_t value)
char serial_number_[2 *(SERIAL_FIRST_HALF_REGS+SERIAL_SECOND_HALF_REGS)+1]
float position
Definition cover.h:0
bool state
Definition fan.h:2
std::optional< ExceptionCode > ResponseStatus
Definition modbus.h:329
uint32_t value
Definition hal.cpp:41
bool valid
static void uint32_t
char serial_number[10]
Definition sun_gtil2.cpp:15