Seich
/
HomeSpan
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
HomeSpan/docs/FAQ.md

8.1 KiB
Raw Blame History

Frequently Asked Questions

A list of answers to frequently-asked-questions, as well as discussions of various topics of interest.

How do I set my WiFi SSID and Password?

  • In the spirit of promoting good security practices, HomeSpan does not allow you to embed your WiFi SSID and Password (collectively known as WiFi Credentials) into your sketch. This eliminates the possibility of accidentally disclosing this information should you share your sketch with others.

  • Instead, HomeSpan stores your WiFi Credentials in a dedicated non-volatile storage (NVS) partition of the ESP32. There are two ways of entering this information. If you are developing a sketch within the Arduino IDE, simply use the HomeSpan Command Line Interface and type 'W' into the Serial Monitor. HomeSpan will prompt you to input your WiFi SSID and Password (see CLI for details). As an alternative, if your HomeSpan device is not connected to a computer, you can launch HomeSpan's Temporary WiFi Setup Network and input your WiFi Credentials directly into the web forms served by your device (see the User Guide for details).

What is the Setup Code used for pairing a HomeSpan device to HomeKit?

  • The HomeSpan default Setup Code is 466-37-726. You can (and should) use the HomeSpan Command Line Interface to change this default to a secret code unique for each of your devices. Simply type 'S <code>' into the Serial Monitor, or specify your desired Setup Code at the outset when configuring your WiFi Credentials using HomeSpan's Temporary WiFi Setup Network.

Can you use more than one HomeSpan device on the same HomeKit network?

  • Yes, multiple ESP32's, each running a separate copy of HomeSpan, can be used on the same HomeKit network, provided that each device has a unique Device ID, a unique Host Name, and a unique Display Name. Normally, the Device ID is randomly-generated by HomeSpan at start-up and will therefore automatically be unique across multiple devices. Also, unless you override the suffix of the default Host Name, it will also be unique across multiple devices since HomeSpan uses the Device ID as the suffix of the Host Name. The only thing you need to ensure is that you assign a different Display Name to each of your devices. See the HomeSpan API Reference for details on how to do this.

Does HomeSpan support video and audio streams?

  • No, HomeSpan does not support streaming services, such as Audio Stream Management, Data Stream Transport Management, or Camera RTP Management. See HomeSpan Services and Characteristics for a complete list of all Services supported by HomeSpan.

Does HomeSpan work with PlatformIO?

  • HomeSpan does not explicitly support PlatformIO but multiple users have reported successfully using the HomeSpan library with PlatformIO.

Will HomeSpan work on an ESP8266 device?

  • No, HomeSpan is coded specifically for the ESP32 and will not operate on an ESP8266 device.

How can I read HomeSpan's MDNS broadcast mentioned in the OTA documentation?

  • HomeSpan uses MDNS (multicast DNS) to broadcast a variety of HAP information used by Controllers wishing to pair with HomeSpan. Apple uses the name Bonjour to refer to MDNS, and originally included a Bonjour "Browser" in Safari that has since been discontinued. However, there are a number of alternative MDNS browsers available for free that operate on both the Mac and the iPhone, such as the Discovery - DNS-SD Browser. You'll find all your HomeSpan devices, as well as any other HomeKit devices you may have, under the MDNS service named _hap._tcp. The fields broadcast by HomeSpan are a combination of all data elements requires by HAP (HAP-R2, Table 6-7) plus three additional HomeSpan fields:

    • hspn - the version number of the HomeSpan library used to compile the sketch
    • sketch - the version number of the sketch, as specified with homeSpan.setSketchVersion(const char *), or n/a if no version was specified
    • ota - either yes or no depending on whether OTA was enabled for the sketch using the method homeSpan.enableOTA()

Does HomeSpan support Television Services?

  • Yes. Though undocumented by Apple and not officially part of HAP-R2, HomeSpan supports HomeKit Television controls. See Television Services for details.

Can you use HomeSpan with an Ethernet connection instead of a WiFi connection?

  • Not as present. Though with a compatible Ethernet board the ESP32 can be configured to run as an Ethernet Server, using MDNS over Ethernet does not work on the ESP32 due to some apparent problems with the Ethernet UDP stack. Unfortunately, HomeSpan and HAP-R2 require MDNS to operate. If anyone has managed to get an Ethernet version of MDNS working on an ESP32 please let me know - it would be great to add Ethernet support to HomeSpan.

Does HomeSpan work with SPI and I2C?

  • Yes, the standard Arduino libraries SPI.h and Wire.h both work well within the HomeSpan environment. Typically the code to read from an SPI or I2C device is implemented within the loop() method of a HomeSpan Service with any initialization being done in the constructor for that Service. See TemperatureSensorI2C for an illustrative example.

Can you add a Web Server to HomeSpan?

  • Yes, provided you implement your Web Server using standard ESP32-Arduino libraries, such as WebServer.h. See ProgrammableHub for an illustrative example of how to easily integrate a Web Server into HomeSpan. This project also covers various other advanced topics, including TCP slot management, dynamic creation of Accessories, and saving arbitrary data in the ESP32's NVS.

Can you add custom Services and Characteristics to HomeSpan?

  • Yes, HomeSpan includes two easy-to-use macros to define your own custom Services and custom Characteristics beyond those specified in HAP-R2. See the HomeSpan API Reference for details and examples demonstrating how to do this. Note that any new Characteristics you create will be completely ignored by the Home App. Similarly, any new Services you create will be shown in the Home App on a tile labeled "Not Supported". Apple does not provide any mechanism to extend the functionality of the Home App itself. However, the place where custom Services and Characteristics can be used is in third-party applications designed for these extra features. For example, the Eve for HomeKit App properly handles all the Services and Characteristics defined in HAP-R2, plus a variety of additional Services and Characteristics designed explictly for use with Eve products. If you know the UUID codes for these extra Services and Characteristics you can add them to HomeKit and use them within the Eve App just as if they were HAP-R2 Services and Characteristics.

Can HomeSpan be used for commercial devices?

  • No, a MFi license is needed to create commercial devices. HomeSpan was developed using Apple's HAP-R2 specs, which Apple provides for non-commercial devices that won't be distributed or sold. Though I believe the commercial specifications are functionally the same, there is a slight, but critical, difference in the pairing protocol between HAP-R2 and MFi. Note that when you pair a HomeSpan device (or any device that is based on HAP-R2, such as Apple's HAP-R2 ADK, Espressif's non-commercial ADK, HomeBridge, etc.) the Home App on your iPhone will flag the device as uncertified and require you to grant it permission to proceed with pairing. This warning message about the device being uncertified does not appear on commercial devices, presumably because Apple provides the licensee with a custom MFi authorization code that is recognized by the iPhone.

↩️ Back to the Welcome page