ESP8266 – HomeKit Firmware Update with EVE

Changing Makefile

To be ablet to execute teh Firmware Update, we need to change some files. Open the Terminal app. Click the Finder icon in your dock. Click Go. Click Utilities. Double-click Terminal. then type:

cd esp

change into folder esp-homekit-demo

cd esp-homekit-demo

then change into the examples folder.

cd examples

Then open a accecory (e.g. Led)

cd led

Now you will see two files:

led.c
makefile

Open makefile with ATOM and change the following line:

PROGRAM = led

EXTRA_COMPONENTS = \
	extras/http-parser \
	$(abspath ../../components/esp8266-open-rtos/cJSON) \
	$(abspath ../../components/common/wolfssl) \
	$(abspath ../../components/common/homekit)

FLASH_SIZE ?= 32

EXTRA_CFLAGS += -I../.. -DHOMEKIT_SHORT_APPLE_UUIDS

include $(SDK_PATH)/common.mk

monitor:
	$(FILTEROUTPUT) --port $(ESPPORT) --baud 115200 --elf $(PROGRAM_OUT)

to

PROGRAM = main

EXTRA_COMPONENTS = \
	extras/http-parser \
        extras/rboot-ota \
	$(abspath ../../components/esp8266-open-rtos/cJSON) \
	$(abspath ../../components/common/wolfssl) \
	$(abspath ../../components/common/homekit)

FLASH_SIZE ?= 32

EXTRA_CFLAGS += -I../.. -DHOMEKIT_SHORT_APPLE_UUIDS

include $(SDK_PATH)/common.mk

monitor:
	$(FILTEROUTPUT) --port $(ESPPORT) --baud 115200 --elf $(PROGRAM_OUT)

Open main.c with ATOM. Inside main.c you should start with adding this section soon after #include section. You need to add this section to make your device OTA capable.It creates  the extra characteristic &ota_trigger, witch is placed at the end of the primary service (before the NULL). This extra characteristic can be used in the Eve app, which will show it, where unfortunately the HomeKit app does not.It will also  apply the four other parameters in the accessories_information section.

#include "ota-api.h"

homekit_characteristic_t ota_trigger  = API_OTA_TRIGGER;
homekit_characteristic_t manufacturer = HOMEKIT_CHARACTERISTIC_(MANUFACTURER,  "X");
homekit_characteristic_t serial       = HOMEKIT_CHARACTERISTIC_(SERIAL_NUMBER, "1");
homekit_characteristic_t model        = HOMEKIT_CHARACTERISTIC_(MODEL,         "Z");
homekit_characteristic_t revision     = HOMEKIT_CHARACTERISTIC_(FIRMWARE_REVISION,  "0.0.0");

Next place these  lines before calling homekit_server_init(&config);

int c_hash=ota_read_sysparam(&manufacturer.value.string_value,&serial.value.string_value,
                                      &model.value.string_value,&revision.value.string_value);
    //c_hash=1; revision.value.string_value="0.0.1"; //cheat line
    config.accessories[0]->config_number=c_hash;;

After all adjustments you should have this in the end.

/*
Copyright 2019 Achim Pieters | StudioPieters®

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
#include <stdio.h>
#include <esp/uart.h>
#include <esp8266.h>
#include <FreeRTOS.h>
#include <task.h>

#include <homekit/homekit.h>
#include <homekit/characteristics.h>
#include <wifi_config.h>

#include "ota-api.h" // Add This Line

const int led_gpio = 2;
bool led_on = false;

void led_write(bool on) {
        gpio_write(led_gpio, on ? 0 : 1);
}

void led_init() {
        gpio_enable(led_gpio, GPIO_OUTPUT);
        led_write(led_on);
}

void led_identify_task(void *_args) {
        for (int i=0; i<3; i++) {
                 for (int j=0; j<2; j++) {
                          led_write(true);
                          vTaskDelay(100 / portTICK_PERIOD_MS);
                          led_write(false);
                          vTaskDelay(100 / portTICK_PERIOD_MS);
                 }
                 vTaskDelay(250 / portTICK_PERIOD_MS);
        }
        led_write(led_on);
        vTaskDelete(NULL);
}

void led_identify(homekit_value_t _value) {
        printf("LED identify\n");
        xTaskCreate(led_identify_task, "LED identify", 128, NULL, 2, NULL);
}

homekit_value_t led_on_get() {
        return HOMEKIT_BOOL(led_on);
}

void led_on_set(homekit_value_t value) {
        if (value.format != homekit_format_bool) {
                printf("Invalid value format: %d\n", value.format);
                return;
        }
        led_on = value.bool_value;
        led_write(led_on);
}

// Add These lines
homekit_characteristic_t ota_trigger = API_OTA_TRIGGER;
homekit_characteristic_t manufacturer = HOMEKIT_CHARACTERISTIC_(MANUFACTURER, "X");
homekit_characteristic_t serial = HOMEKIT_CHARACTERISTIC_(SERIAL_NUMBER, "1");
homekit_characteristic_t model = HOMEKIT_CHARACTERISTIC_(MODEL, "Z");
homekit_characteristic_t revision = HOMEKIT_CHARACTERISTIC_(FIRMWARE_REVISION, "0.0.0");

homekit_accessory_t *accessories[] = {
        HOMEKIT_ACCESSORY(.id=1, .category=homekit_accessory_category_sensor, .services=(homekit_service_t*[]) {
               HOMEKIT_SERVICE(ACCESSORY_INFORMATION, .characteristics=(homekit_characteristic_t*[]) {
                      HOMEKIT_CHARACTERISTIC(NAME, "Sample LED"),
                      &manufacturer,
                      &serial,
                      &model,
                      &revision,
                      HOMEKIT_CHARACTERISTIC(IDENTIFY, led_identify),
                      NULL
               }),
               HOMEKIT_SERVICE(LIGHTBULB, .primary=true, .characteristics=(homekit_characteristic_t*[]){
                      HOMEKIT_CHARACTERISTIC(NAME, "Sample LED"),
                      HOMEKIT_CHARACTERISTIC(
                             ON, false,
                            .getter=led_on_get,
                            .setter=led_on_set,
                             ),
                             &ota_trigger, // Add This Line
                             NULL
                      }),
                      NULL
                }),
                NULL
};

homekit_server_config_t config = {
       .accessories = accessories,
       .password = "123-45-678",
       .setupId="1QJ8",
};

void on_wifi_ready() {
}

void user_init(void) {
         uart_set_baud(0, 115200);
         led_init();
         // Add These lines
         int c_hash=ota_read_sysparam(&manufacturer.value.string_value,&serial.value.string_value,
                                      &model.value.string_value,&revision.value.string_value);
         //c_hash=1; revision.value.string_value="0.0.1"; //cheat line
         config.accessories[0]->config_number=c_hash;

         homekit_server_init(&config);
}

The preparation

Assuming that you have already made one or more devices, I assume that you know how to install your ESP module and connect it to HomeKit, if not then you should start here first. For test propose I have setup a GitHub repository with 2 bin versions eg. version 0.0.1 and 0.0.2. Version 0.0.1 is Latest released and is used to install your ESP module. Version 0.0.2 is setup as Pre-release. When my ESP module is installed I will set version 0.0.2 to a released version and toggle the update button in the Eve App. Now when everything works well it updates the firmware from 0.0.1 to 0.0.2.

The test

At first we are going to add our new made accessory with EVE Firmware update capability. Click Add Accessory to add you device.

Thes scan the QR-Code for more information about ESP HomeKit QR-Code look here.

Then you will see that HomeKit tase found your device and is connected successfully, Click Next.

Ik will show you your new added accessory in your default room, select your accessory and open it.

Go to the accessory information screen by tapping the gear icon in the lower right corner.

Her you see all information about your newly adde device. As you can see are some line file with information form my git repository.

• Manufacturer: Name of the Git Owner
• Serial Number:  Is the Mac address from your ESP module.
• Model: Is the name of the Git repository
• Firmware: This is the release number af the installed version that is release at this moment.

Now it’s time to Release our version 0.0.2 that we placed as a Pre-release on our git. Open your GitHub page and go to release 0.0.2. Remove The tick at This is a pre-release, and the click Update release.

Now you will see that 0.0.2 is no longer a pre-release, but turned into the Latest release.

Open your previous installed EVE app. Here also you will see your added accessory just like in HomeKit. Select it to see the accessory properties.

Here you will see a option called Firmware Update, for whom used the EVE app before will notice this is a new feature.

Turn ON the Firmware Update option and wait a few minutes. You will notice when the Firmware update is completed the ON button will automatically turn back to OFF.

Then close the Eve app and open you HomeKit app, once again go to the accessory information screen. As you can see the firmware version is updated to version 0.0.2!