How to develop a new platform for switches and lights, with event-driven status updates

I am trying to add support for a currently unsupported class of device. It includes lights and switches. I can easily control the lights and switches using one of the existing platforms. Using REST, for example, allows me to send commands to these devices by implementing a web server (to handle the REST calls), which in turn sends commands to a node.js based driver for the devices.

But I have two issues:

  1. How to get “events” from these devices back to HA (i.e. when someone physically turns on a switch, HA needs to know, so it can update its internal status for that switch). Note that I don’t want to poll for status updates.
  2. I’d like to eliminate the separate web server and node.js code, instead moving to a python-based driver with “tighter” integration with HA (porting the driver to python isn’t the problem).

For (#2), it’s my understanding (from https://home-assistant.io/developers/add_new_platform) that what’s needed is a new “platform” script. I think starting with something like https://github.com/home-assistant/home-assistant/tree/master/homeassistant/components/switch or /light is what’s needed for the control part (right?).

But what about “events” (#1)? It does not appear to me that these “platform” scripts handle this “event” feedback. So does that mean I also need to write a platform script here (https://github.com/home-assistant/home-assistant/tree/master/homeassistant/components/sensor)? Or do the switch and light scripts handle the “events” (if so, what’s a good/clean example of one that does this)?

I’ve read just about everything I could find that relates to HA and platforms, but I’m just not clear on exactly what needs to be written. A switch and light scripts, and a sensor script? Or something else entirely?

No, yes, the platform code also (can) handle external events coming in to update the state if it’s being updated from outside home assistant. How they do that is very specific to the device in question. Some schedule a regular task to just poll the device and then generate an event if something changes. You didn’t say how your device is connected, but for modern home-assistant you’ll probably want some async I/O waits for actions on a file descriptor or socket?

Your device has both lights and switches and these are distinct? The most apropos example that comes to my mind is the Tellstick integration (mostly because I have one): https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/tellstick.py is common code that interfaces to an external library, which does the actual heavylifting of communicating with the hardware (well, middleware in this case). Crucially, in _setup_tellcore_callback() it’s registering a callback that will be called from the external library if something changes, which looks up the device object that’s affected and calls its update_from_callback() method. This common code is used in https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/light/tellstick.py and https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/switch/tellstick.py