| 1 | # ex:ts=8 sw=4: | ||
| 2 | # $OpenBSD$ | ||
| 3 | # | ||
| 4 | # Copyright (c) 2025 Dick Olsson <hi@senzilla.io> | ||
| 5 | # | ||
| 6 | # Permission to use, copy, modify, and distribute this software for any | ||
| 7 | # purpose with or without fee is hereby granted, provided that the above | ||
| 8 | # copyright notice and this permission notice appear in all copies. | ||
| 9 | # | ||
| 10 | # THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||
| 11 | # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||
| 12 | # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||
| 13 | # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||
| 14 | # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||
| 15 | # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||
| 16 | # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||
| 17 | |||
| 18 | use v5.36; | ||
| 19 | |||
| 20 | package App::OpenHAP::Devices; | ||
| 21 | our $VERSION = '0.1.0'; | ||
| 22 | |||
| 23 | use Fugu::Log; | ||
| 24 | |||
| 25 | # App::OpenHAP::Devices - turn the device blocks of the configuration | ||
| 26 | # into accessories on the bridge. | ||
| 27 | # | ||
| 28 | # One table describes every device type. Each entry says what the type | ||
| 29 | # is called in a log line, which class builds it, and what that class | ||
| 30 | # needs beyond the fields every device has. Adding a type is one | ||
| 31 | # entry, and no second place to keep true. | ||
| 32 | # | ||
| 33 | # The class of the entry does the work of building. The loader only | ||
| 34 | # decides which one, validates the fields the configuration must | ||
| 35 | # carry, and subscribes the result to MQTT. | ||
| 36 | # | ||
| 37 | # A device class loads when the configuration asks for it, not at | ||
| 38 | # compile time. The classes drag JSON::XS and the whole accessory | ||
| 39 | # model behind them, and a tool that only reads the device blocks | ||
| 40 | # needs none of it. The daemon builds its devices before it pledges, | ||
| 41 | # thus the late load costs it nothing. | ||
| 42 | # The lightbulb family differs only in its capability mask, so those | ||
| 43 | # entries carry a caps field instead of one closure each. The mask | ||
| 44 | # values are the CAP_* constants of the class, spelled as numbers | ||
| 45 | # here because the class loads only when the configuration asks for | ||
| 46 | # it: dimmer 1, color 2, ct 4. | ||
| 47 | my %DEVICE = ( | ||
| 48 | 'tasmota/thermostat' => { | ||
| 49 | name => 'thermostat', | ||
| 50 | class => 'App::OpenHAP::Tasmota::Thermostat', | ||
| 51 | args => sub ($device) { | ||
| 52 | return ( | ||
| 53 | sensor_type => $device->{sensor_type}, | ||
| 54 | sensor_index => $device->{sensor_index}, | ||
| 55 | ); | ||
| 56 | }, | ||
| 57 | }, | ||
| 58 | 'tasmota/heater' => { | ||
| 59 | name => 'switch', | ||
| 60 | class => 'App::OpenHAP::Tasmota::Heater', | ||
| 61 | }, | ||
| 62 | 'tasmota/sensor' => { | ||
| 63 | name => 'sensor', | ||
| 64 | class => 'App::OpenHAP::Tasmota::Sensor', | ||
| 65 | args => sub ($device) { | ||
| 66 | return ( | ||
| 67 | sensor_type => $device->{sensor_type}, | ||
| 68 | sensor_index => $device->{sensor_index}, | ||
| 69 | has_humidity => $device->{has_humidity} // 0, | ||
| 70 | ); | ||
| 71 | }, | ||
| 72 | }, | ||
| 73 | 'tasmota/lightbulb' => { | ||
| 74 | name => 'lightbulb', | ||
| 75 | class => 'App::OpenHAP::Tasmota::Lightbulb', | ||
| 76 | caps => 1, | ||
| 77 | }, | ||
| 78 | 'tasmota/rgblight' => { | ||
| 79 | name => 'rgb light', | ||
| 80 | class => 'App::OpenHAP::Tasmota::Lightbulb', | ||
| 81 | caps => 1 | 2, | ||
| 82 | }, | ||
| 83 | 'tasmota/ctlight' => { | ||
| 84 | name => 'ct light', | ||
| 85 | class => 'App::OpenHAP::Tasmota::Lightbulb', | ||
| 86 | caps => 1 | 4, | ||
| 87 | }, | ||
| 88 | ); | ||
| 89 | |||
| 90 | # Two names for existing entries | ||
| 91 | $DEVICE{'tasmota/switch'} = $DEVICE{'tasmota/heater'}; | ||
| 92 | $DEVICE{'tasmota/dimmer'} = $DEVICE{'tasmota/lightbulb'}; | ||
| 93 | |||
| 94 | # $class->new(): | ||
| 95 | # Create a new device loader instance. | ||
| 96 | sub new ($class) | ||
| 97 | { | ||
| 98 | bless { | ||
| 99 | next_aid => 2, # AID 1 is the bridge | ||
| 100 | devices => [], | ||
| 101 | }, $class; | ||
| 102 | } | ||
| 103 | |||
| 104 | # $self->load_devices($config, $hap, $mqtt): | ||
| 105 | # Load the devices from the configuration. Add them to the | ||
| 106 | # HAP bridge. The method returns the number of loaded devices. | ||
| 107 | sub load_devices ( $self, $config, $hap, $mqtt ) | ||
| 108 | { | ||
| 109 | my @devices = $self->devices($config); | ||
| 110 | Fugu::Log->default->debug( 'Loading %d device(s) from configuration', | ||
| 111 | scalar @devices ); | ||
| 112 | |||
| 113 | my $loaded_count = 0; | ||
| 114 | my $mqtt_connected = $mqtt->is_connected(); | ||
| 115 | |||
| 116 | for my $device (@devices) { | ||
| 117 | my $accessory = | ||
| 118 | $self->_create_device( $device, $mqtt, $mqtt_connected ); | ||
| 119 | next unless defined $accessory; | ||
| 120 | |||
| 121 | $hap->add_accessory($accessory); | ||
| 122 | push @{ $self->{devices} }, $accessory; | ||
| 123 | $loaded_count++; | ||
| 124 | |||
| 125 | Fugu::Log->default->info( | ||
| 126 | 'Added %s: %s (AID=%d)', | ||
| 127 | $self->_device_type_name($device), | ||
| 128 | $device->{name}, $accessory->{aid} ); | ||
| 129 | } | ||
| 130 | |||
| 131 | Fugu::Log->default->info( 'Loaded %d device(s), %d skipped', | ||
| 132 | $loaded_count, scalar(@devices) - $loaded_count ); | ||
| 133 | |||
| 134 | return $loaded_count; | ||
| 135 | } | ||
| 136 | |||
| 137 | # $self->get_devices(): | ||
| 138 | # Return the list of loaded device accessory objects. | ||
| 139 | sub get_devices ($self) | ||
| 140 | { | ||
| 141 | return @{ $self->{devices} }; | ||
| 142 | } | ||
| 143 | |||
| 144 | # $self->_create_device($device, $mqtt, $mqtt_connected): | ||
| 145 | # Create an accessory from the device configuration. | ||
| 146 | # The method returns the accessory object, or undef on error. | ||
| 147 | sub _create_device ( $self, $device, $mqtt, $mqtt_connected ) | ||
| 148 | { | ||
| 149 | my $dev_type = $device->{type} // 'unknown'; | ||
| 150 | my $dev_subtype = $device->{subtype} // 'unknown'; | ||
| 151 | |||
| 152 | Fugu::Log->default->debug( | ||
| 153 | 'Processing device: type=%s, subtype=%s, name=%s', | ||
| 154 | $dev_type, $dev_subtype, $device->{name} // '<unnamed>' ); | ||
| 155 | |||
| 156 | # Validate the device type. The one lookup serves the check, | ||
| 157 | # the build, and the log name. | ||
| 158 | my $entry = $DEVICE{"$dev_type/$dev_subtype"}; | ||
| 159 | unless ($entry) { | ||
| 160 | Fugu::Log->default->debug( | ||
| 161 | 'Skipping unsupported device type: %s/%s', | ||
| 162 | $dev_type, $dev_subtype ); | ||
| 163 | return; | ||
| 164 | } | ||
| 165 | |||
| 166 | # Validate the required fields | ||
| 167 | return unless $self->_validate_device($device); | ||
| 168 | |||
| 169 | # Create the device and catch errors | ||
| 170 | my $accessory; | ||
| 171 | eval { | ||
| 172 | $accessory = | ||
| 173 | $self->_instantiate_device( $device, $mqtt, $entry ); | ||
| 174 | }; | ||
| 175 | if ($@) { | ||
| 176 | Fugu::Log->default->error( 'Failed to create %s "%s": %s', | ||
| 177 | $entry->{name}, $device->{name}, $@ ); | ||
| 178 | return; | ||
| 179 | } | ||
| 180 | |||
| 181 | # Subscribe to MQTT if the client is connected | ||
| 182 | if ($mqtt_connected) { | ||
| 183 | $self->_subscribe_mqtt( $accessory, $device ); | ||
| 184 | } | ||
| 185 | else { | ||
| 186 | Fugu::Log->default->debug( | ||
| 187 | 'MQTT not connected, deferring subscription for "%s"', | ||
| 188 | $device->{name} ); | ||
| 189 | } | ||
| 190 | |||
| 191 | return $accessory; | ||
| 192 | } | ||
| 193 | |||
| 194 | # $class->devices($config): | ||
| 195 | # Return the device blocks of a Fugu::Config as records with | ||
| 196 | # type, subtype, id and the settings of the block. | ||
| 197 | sub devices ( $, $config ) | ||
| 198 | { | ||
| 199 | my @devices; | ||
| 200 | for my $block ( $config->blocks('device') ) { | ||
| 201 | my ( $type, $subtype, $id ) = @{ $block->{args} }; | ||
| 202 | push @devices, | ||
| 203 | { | ||
| 204 | %{ $block->{settings} }, | ||
| 205 | type => $type, | ||
| 206 | subtype => $subtype, | ||
| 207 | id => $id, | ||
| 208 | }; | ||
| 209 | } | ||
| 210 | |||
| 211 | return @devices; | ||
| 212 | } | ||
| 213 | |||
| 214 | # $self->_validate_device($device): | ||
| 215 | # Validate the required device fields. The method returns true | ||
| 216 | # if the device is valid. | ||
| 217 | sub _validate_device ( $self, $device ) | ||
| 218 | { | ||
| 219 | unless ( defined $device->{name} && $device->{name} ne '' ) { | ||
| 220 | Fugu::Log->default->error( | ||
| 221 | 'Device missing required field: name'); | ||
| 222 | return; | ||
| 223 | } | ||
| 224 | |||
| 225 | unless ( defined $device->{topic} && $device->{topic} ne '' ) { | ||
| 226 | Fugu::Log->default->error( | ||
| 227 | 'Device "%s" missing required field: topic', | ||
| 228 | $device->{name} ); | ||
| 229 | return; | ||
| 230 | } | ||
| 231 | |||
| 232 | unless ( defined $device->{id} && $device->{id} ne '' ) { | ||
| 233 | Fugu::Log->default->warning( | ||
| 234 | 'Device "%s" missing id field, using topic as serial', | ||
| 235 | $device->{name} ); | ||
| 236 | $device->{id} = $device->{topic}; | ||
| 237 | } | ||
| 238 | |||
| 239 | return 1; | ||
| 240 | } | ||
| 241 | |||
| 242 | # $self->_instantiate_device($device, $mqtt, $entry): | ||
| 243 | # Create the device object for a %DEVICE entry. | ||
| 244 | sub _instantiate_device ( $self, $device, $mqtt, $entry ) | ||
| 245 | { | ||
| 246 | # The class loads here, not at compile time. require needs the | ||
| 247 | # path form of the name. | ||
| 248 | my $module = $entry->{class} =~ s{::}{/}gr; | ||
| 249 | require "$module.pm"; | ||
| 250 | |||
| 251 | my %args = ( | ||
| 252 | aid => $self->{next_aid}++, | ||
| 253 | name => $device->{name}, | ||
| 254 | mqtt_topic => $device->{topic}, | ||
| 255 | mqtt_client => $mqtt, | ||
| 256 | serial => $device->{id}, | ||
| 257 | relay_index => $device->{relay_index} // 0, | ||
| 258 | |||
| 259 | # The model logs through the injected logger. The device | ||
| 260 | # passes it on to every service and characteristic it | ||
| 261 | # builds, so the write and subscription debug lines keep | ||
| 262 | # reaching the daemon log. | ||
| 263 | logger => Fugu::Log->default, | ||
| 264 | ); | ||
| 265 | $args{capabilities} = $entry->{caps} if defined $entry->{caps}; | ||
| 266 | %args = ( %args, $entry->{args}->($device) ) if $entry->{args}; | ||
| 267 | |||
| 268 | return $entry->{class}->new(%args); | ||
| 269 | } | ||
| 270 | |||
| 271 | # $self->_subscribe_mqtt($accessory, $device): | ||
| 272 | # Subscribe the device to its MQTT topics. | ||
| 273 | sub _subscribe_mqtt ( $self, $accessory, $device ) | ||
| 274 | { | ||
| 275 | eval { $accessory->subscribe_mqtt(); }; | ||
| 276 | if ($@) { | ||
| 277 | Fugu::Log->default->error( | ||
| 278 | 'Failed to subscribe MQTT for "%s": %s', | ||
| 279 | $device->{name}, $@ ); | ||
| 280 | } | ||
| 281 | else { | ||
| 282 | Fugu::Log->default->info( 'Subscribed to MQTT topic: %s', | ||
| 283 | $device->{topic} ); | ||
| 284 | } | ||
| 285 | } | ||
| 286 | |||
| 287 | # $self->_device_type_name($device): | ||
| 288 | # Return the human-readable device type name. Every caller has | ||
| 289 | # already passed the %DEVICE lookup, so the entry is there. | ||
| 290 | sub _device_type_name ( $self, $device ) | ||
| 291 | { | ||
| 292 | return $DEVICE{"$device->{type}/$device->{subtype}"}{name}; | ||
| 293 | } | ||
| 294 | |||
| 295 | 1; |