Skip to content

[Experimental] Add HomeKit support based on HomeSpan for the ONE. - #392

Draft
seansfkelley wants to merge 1 commit into
Open-Air-Foundation:masterfrom
seansfkelley:homekit
Draft

[Experimental] Add HomeKit support based on HomeSpan for the ONE.#392
seansfkelley wants to merge 1 commit into
Open-Air-Foundation:masterfrom
seansfkelley:homekit

Conversation

@seansfkelley

Copy link
Copy Markdown

Summary and Features

This PR adds support for reporting to HomeKit using HomeSpan for the ONE. (It is the only one I have and so the only one I tested.)

When set up, the ONE reports all the readings it has, with some caveats (see below). It appears in HomeKit as little pills, since it's a read-only sensor and not an interactive thing.

Screenshot 2026-07-27 at 10 29 57

To try it out, after flashing this firmware, pair with the code 466-37-726 (HomeSpan's default value).

Technical Details and Caveats

This PR has significant shortcomings, however, so it needs input from other HomeKit users (i.e. what they want) and AirGradient (i.e. what is acceptable) if it is to be incorporated upstream. That said, I'm opening this PR for discoverability for other potential HomeKit tinkerers.

The major caveats are:

  • HomeSpan adds ~200KB, which pushes the binary size over the 1.9MB limit. (See also ONE firmware boot-loops when following howto-compile.md instructions, with suggested resolution #386.) This PR switches to the "Huge APP" configuration, which disables OTA updates due to lack of space.
  • HomeKit wants absolute ug/m3 measurements for VOC and NOx, but the ONE only reports relative indices. This PR just reports the index as if it's the concentration. (Also HomeKit uses the terminology "NO2", not the broader "NOx".)

And these aren't really caveats so much as things to be aware of/corners I cut temporarily:

  • The air quality index is currently reported as the max of the CO2/PM2.5 index because I didn't want to go down the rabbit hole of computing the full formulas.
  • HomeSpan is pegged to 1.9.1 because that's the last version that supports this board.
  • I had to configure HomeSpan with a non-default port (here, 1201) because otherwise it would fight with the API server on 80.
  • HomeKit hides the specific readings (like PM2.5) behind a tap, which is annoying if you want the details up-front, and I can't figure out how to configure it otherwise. For some reason it also lists the CO2 sensor as just "Carbon Dioxide Sensor" without giving you figures until you tap into it. Perhaps third-party HomeKit viewers (Eve?) don't have this problem.


// HomeKit pairing (SRP) is stack-heavy; enlarge the Arduino loop-task stack so
// homeSpan.poll() has room to complete pairing without a stack overflow.
SET_LOOP_TASK_STACK_SIZE(16 * 1024);

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this is actually necessary. Would check it again before committing to it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant