Repository files navigation

中文说明 |Português Brasileiro |Русский

This Arduino library is a native Apple HomeKit accessory implementation for theESP8266 Arduino core, and works without any additional bridges.

This project is mainly based onesp-homekit forESP-OPEN-RTOS.

I ported the RTOS-based implementation ofesp-homekit to the pure Arduino environment, aimed at easy and fast building project using Arduino IDE (or Eclipse with sloeber, PlatformIO).

Enjoy the "one-key" build, "one-key" upload, and work to link various other Arduino libraries with Apple HomeKit!

Here is adiscussion about the RTOS is required for running Apple HomeKit, and this project is a proof of concept that Apple HomeKit can be implemented and work fine without the RTOS.

This library is built with ESP8266 Arduino Core 2.6.3. Lower versions may compile with errors.

For ESP32, seeArduino-HomeKit-ESP32. The HomeKit running on ESP32 has aGREAT PERFORMANCE which is 10x faster than ESP8266.

111-11-111

1. Define your accessory in a .c file to enjoy the convenient "Macro" style declaration. You can also define your accessory in a .ino file using C++ code.

   homekit_accessory_t*accessories[]= ...homekit_server_config_tconfig= {.accessories=accessories,.password="111-11-111",//.on_event = on_homekit_event, //optional//.setupId = "ABCD" //optional};

2. In your sketch

   #include<arduino_homekit_server.h>;//access the config defined in C codeextern"C"homekit_server_config_tconfig;voidsetup() {WiFi.begin(ssid,password);arduino_homekit_setup(&config);}voidloop() {arduino_homekit_loop();}

Done.

Notice: You should set the ESP8266 CPU to run at 160MHz (at least during the pairing process), to avoid the tcp-socket disconnection from iOS device caused by timeout.

• Preinit: ~9.1s (You can see the accessory on your iOS HOME app after Preinit)
• Pair Setup Step 1/3: ~0s (The heavy crypto computation is done in Preinit)
• Pair Setup Step 2/3: ~12.1s
• Pair Setup Step 3/3: ~0.8s (The pair-setup is only processed when first paired with iOS device)
• Pair Verify Step 1/2: ~0.3s
• Pair Verify Step 2/2: ~0.8s (The Verify Step is required every time iOS connects or reconnects to ESP8266 to establish secure session)

All pairing process takes ~14s after you input the setup-code on your iPhone. Notice that Preinit require ~9s before you can start to pair.

The heap is critical for ESP8266 with full TCP/IP support. ESP8266 easily crashes when the memory is lower than ~5000.

I tried to make WolfSSL crypto work safely on ESP8266 with better performance and lower memory or a trade-off. See details in next section.

Here are the free heap values of running the example sketch:

• Boot: ~26000
• Preinit over: ~22000
• Pairing: ~17000 (or even low when crypto computing)
• Paired and connected with one iOS device: ~21700
• Paired and no iOS device connected: ~23400

After memory optimization in v1.1.0:

• Boot: ~46000
• Preinit over: ~41000
• Pairing: ~37000 (or even low when crypto computing)
• Paired and connected with one iOS device: ~41700
• Paired and no iOS device connected: ~43000

• Based on wolfssl-3.13.0-stable.
• Clean source code: the unused files are removed.
• CURVE25519_SMALL andED25519_SMALL: ESP8266 can not directly run withoutSMALL defined since the memory is not sufficient. But the NOSMALL version is faster. I mark the bigge_precomp base[32][8] with PROGMEM to store it in Flash (around 70KB). Also thege_double_scalarmult_vartime can not run caused by lack of heap. I defineESP_GE_DOUBLE_SCALARMULT_VARTIME_LOWMEM inuser_settings.h to use LOWMEM version ofge_double_scalarmult_vartime inge_low_mem.c. This is a trade-off of performance and memory. If you want more Flash space, you should defineCURVE25519_SMALL andED25519_SMALL and undefineESP_GE_DOUBLE_SCALARMULT_VARTIME_LOWMEM inuser_settings.h (this will lead the Pair Verify Steps to take 1.2s + 0.9s).
• integer.c(big integer operations):MP_16BIT andESP_FORCE_S_MP_EXPTMOD are defined for better performance in ESP8266.ESP_INTEGER_WINSIZE (value is 3) is defined to avoid crash caused by memory exhaust and the values of {3, 4, 5} are of similar performance.

• The pairing data is stored in theEEPROM address in ESP8266 Arduino core.
• This project does not use theEEPROM library with data-cache to reduce memory use (directly call flash_read and write).
• TheEEPROM is 4096B in ESP8266, this project uses max [0, 1408B).
• See the comments instorge.c andESP8266-EEPROM-doc.
• EEPROM of [1408, 4096) is safe for you to use.
• This project do NOT useFS(file system), so you can useFS freely.

• There are software and hardware watchdogs in ESP8266 Arduino core. The heavy crypto computing will lead to watchdog reset.
• There are disable/enable api of software-watchdog in ESP8266 Arduino core.
• I found theesp_hw_wdt to disable/enable the hardware-watchdog.
• The two watchdogs are disabled whilePreinit andPair Setup Step 2/3.

• Module: Generic ESP8266 Module (to enable full settings)
• FlashSize: at least 470KB for sketch (seeWolfSSL section if you want a smaller sketch)
• LwIP Variant: v2 Lower Memory (for lower memory use)
• Debug Level: None (for lower memory use)
• Espressif FW: nonos-sdk 2.2.1+119(191122) (which I used to build this project)
• SSL Support: Basic SSL ciphers (lower ROM use)
• VTables: Flash (does not matter maybe)
• Erase Flash: selectAll Flash Contents when you first upload
• CPU Frequency: 160MHz (must)

• ESP8266WiFi (WiFiServer and WiFiClient) is used for tcp connection.
• ESP8266mDNS is used for advertising (Bonjour)

• Check your serial output withexample_serial_output.txt

• Addyield() while crypto computing, to prevent WiFi disconnection. The idea is fromBbIKTOP-issues80
• One new example.

• Small improvements.

• New examples.

• Memory optimization: moved String/byte constants as much as possible to Flash. TheRODATA section ofbin is only 4672. Extra ~20K free-heap is available compared with v1.0.1.
• UploadESP8266WiFi_nossl_noleak, anossl andnoleak version of the officialESP8266WiFi library of Arduino Core 2.6.3. Removed all codes ofSSL to save memory (extra ~3K) since the HomeKit does not require SSL. Fix the memory-leak inWiFiClinet.stop() by addingtcp_abandon(_pcb, 0) instop(), based on the idea ofesp8266/Arduino/pull/2767.

• Reducewinsize from3 to2(same performance) to lower the heap required. Pairing can be done with low free-heap of ~14000.
• Specify the MDNS runs on the IPAddress of STA to ensure the HomeKit can work with some SoftAP-based WiFi-Config libraries.
• Rename theHTTP_METHOD(s) inhttp_parser.h to avoid multi-definition errors when usingESP8266WebServer together.

• esp-homekit
• esp-homekit-demo
• esp_hw_wdt
• WolfSSL/WolfCrypt
• cJSON
• cQueue