Poor Documentation
Device integration APIs, if provided at all, are poorly documented and typically unsupported by manufacturers.
The Problem
Even when HEI devices expose local APIs, integrating with them is often an exercise in frustration. Documentation is incomplete, outdated, or simply doesn't exist. And when you run into problems, there's no support channel.
Common Documentation Issues
No Official Documentation
Many devices have local APIs that exist but are completely undocumented. The only way to discover them is through network sniffing, reverse engineering, or finding community-maintained unofficial documentation.
Example: Tesla Local API
The Tesla Powerwall Gateway has a local REST API that exposes extensive data about your system. However, Tesla provides no official documentation. Everything known about the API comes from community reverse-engineering efforts.
Consequences:
- Endpoints discovered by trial and error
- Response formats change without notice in firmware updates
- Authentication methods have changed multiple times
- No official support when integrations break
Incomplete Documentation
Some vendors provide documentation that covers basic functionality but omits important details:
- Error codes and their meanings
- Rate limits and how to avoid them
- Authentication token lifetimes and refresh procedures
- Which fields are optional vs required
- Units of measurement for numeric values
- Valid ranges for settable parameters
Outdated Documentation
Documentation that existed when the product launched may not be updated as firmware evolves:
- New endpoints added but not documented
- Old endpoints deprecated without notice
- Response schemas change, breaking integrations
- New authentication requirements introduced
The "Unsupported" Problem
Even when documentation exists, many manufacturers explicitly label local APIs as "unsupported" - meaning:
- No guarantee of stability between firmware versions
- No support channel for integration issues
- APIs may be removed at any time
- Using them may void your warranty (though rarely enforced)
The Integration Developer Experience
Typical integration development process:
- Search online for "[device] local API"
- Find a 3-year-old GitHub repo with partial documentation
- Discover half the endpoints no longer work
- Sniff network traffic from the mobile app
- Guess at authentication requirements
- Trial-and-error to figure out request formats
- Build working integration
- Firmware update breaks everything
- Return to step 4
Why This Happens
- Support costs: Documented APIs create support expectations
- Liability concerns: Third-party integrations could cause safety issues
- Business model: Manufacturers want control over integrations
- Resource constraints: Documentation isn't prioritized
- Cloud preference: Manufacturers prefer cloud APIs they control
Impact on the Ecosystem
- Integration developers waste time reverse-engineering
- Integrations are fragile and break with updates
- Community knowledge is scattered and incomplete
- Innovation is stifled by uncertainty
- Homeowners can't rely on third-party integrations
How eBus Solves This
eBus devices are required to be self-documenting. The Homie Convention mandates that devices publish their schema directly to MQTT topics, including:
- All available properties and their data types
- Units of measurement for numeric values
- Valid ranges and enumeration values
- Whether properties are readable, writable, or both
- Device state and lifecycle information
A client connecting to an eBus broker can discover everything it needs to integrate with any device - no external documentation required. The schema is always current because it comes directly from the device.