A-HAP Setup Guide

1. Default Login

After installing A-HAP, open the web interface in your browser.

On the same machine:

From another device on the same network:

2. Device Compatibility

A-HAP is designed for ESP32-based automation controllers. The default sketch below is written for ESP32 development boards because it uses ESP32 Wi-Fi and HTTP libraries.

Other network-capable GPIO devices may also work with A-HAP if they can call the A-HAP HTTP endpoint and control GPIO pins. This may include some Arduino-compatible boards, but standard Arduino boards may require adapted code and different Wi-Fi or network libraries.

3. What You Need

• An ESP32 development board.
• A USB cable suitable for the ESP32 board.
• Arduino IDE installed on your computer.
• The ESP32 connected to the same network as the A-HAP server.
• The IP address of the computer, Raspberry Pi, or server running A-HAP.

4. Install Arduino IDE

Download Arduino IDE from the official Arduino documentation page: https://docs.arduino.cc/software/ide/

1. Install Arduino IDE on your computer.
2. Open Arduino IDE.
3. Go to File > Preferences.
4. Find Additional boards manager URLs.
5. Add this URL:

6. Click OK.
7. Go to Tools > Board > Boards Manager.
8. Search for esp32.
9. Install esp32 by Espressif Systems.

5. Install Required Arduino Libraries

In Arduino IDE, go to Sketch > Include Library > Manage Libraries.

Install this library:

• ArduinoJson by Benoit Blanchon

The following libraries are normally included with the ESP32 board package:

• WiFi
• HTTPClient

6. Connect the ESP32

1. Connect the ESP32 to your computer using USB.
2. Open Arduino IDE.
3. Select your ESP32 board from Tools > Board.
4. Select the correct USB port from Tools > Port.

For many standard ESP32 development boards, ESP32 Dev Module is a suitable board option.

7. Create a Role and Output in A-HAP

1. Log in to A-HAP.
2. Create a Role for the ESP32 board.
3. Note the Role ID. This is used as the board ID in the ESP32 sketch.
4. Create one or more outputs under that Role.
5. Set the GPIO pin number for each output.

Example:

8. Default ESP32 Sketch

Update the Wi-Fi name, Wi-Fi password, A-HAP server IP address, board ID, and GPIO pins before uploading.

#include <WiFi.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>

const char* WIFI_SSID = "YOUR_WIFI_NAME";
const char* WIFI_PASSWORD = "YOUR_WIFI_PASSWORD";

// Change this to the IP address of the computer/server running A-HAP.
const char* AHAP_SERVER_IP = "192.168.1.100";
const int AHAP_SERVER_PORT = 5233;

// This must match the Role ID created in A-HAP.
const int BOARD_ID = 1;

// Polling interval in milliseconds.
const unsigned long POLL_INTERVAL_MS = 2000;

// Add the GPIO pins you want this ESP32 to control.
const int OUTPUT_PINS[] = { 2 };
const int OUTPUT_PIN_COUNT = sizeof(OUTPUT_PINS) / sizeof(OUTPUT_PINS[0]);

unsigned long lastPollTime = 0;

void setAllOutputsOff()
{
    for (int i = 0; i < OUTPUT_PIN_COUNT; i++)
    {
        digitalWrite(OUTPUT_PINS[i], LOW);
    }
}

bool isManagedPin(int pin)
{
    for (int i = 0; i < OUTPUT_PIN_COUNT; i++)
    {
        if (OUTPUT_PINS[i] == pin)
        {
            return true;
        }
    }

    return false;
}

void connectToWiFi()
{
    if (WiFi.status() == WL_CONNECTED)
    {
        return;
    }

    Serial.println("Connecting to Wi-Fi...");

    WiFi.mode(WIFI_STA);
    WiFi.setSleep(false);
    WiFi.begin(WIFI_SSID, WIFI_PASSWORD);

    unsigned long startAttempt = millis();

    while (WiFi.status() != WL_CONNECTED && millis() - startAttempt < 20000)
    {
        delay(500);
        Serial.print(".");
    }

    Serial.println();

    if (WiFi.status() == WL_CONNECTED)
    {
        Serial.print("Connected. ESP32 IP: ");
        Serial.println(WiFi.localIP());
    }
    else
    {
        Serial.println("Wi-Fi connection failed. Outputs remain OFF.");
        setAllOutputsOff();
    }
}

void pollAhapServer()
{
    if (WiFi.status() != WL_CONNECTED)
    {
        setAllOutputsOff();
        connectToWiFi();
        return;
    }

    String url = "http://";
    url += AHAP_SERVER_IP;
    url += ":";
    url += AHAP_SERVER_PORT;
    url += "/api/esp/outputs?board=";
    url += BOARD_ID;

    HTTPClient http;
    http.begin(url);

    int httpCode = http.GET();

    if (httpCode == 200)
    {
        String payload = http.getString();

        StaticJsonDocument<512> doc;
        DeserializationError error = deserializeJson(doc, payload);

        if (error)
        {
            Serial.print("JSON parse failed: ");
            Serial.println(error.c_str());
            setAllOutputsOff();
            http.end();
            return;
        }

        setAllOutputsOff();

        JsonObject obj = doc.as<JsonObject>();

        for (JsonPair kv : obj)
        {
            int gpioPin = atoi(kv.key().c_str());
            int state = kv.value().as<int>();

            if (isManagedPin(gpioPin))
            {
                digitalWrite(gpioPin, state == 1 ? HIGH : LOW);

                Serial.print("GPIO ");
                Serial.print(gpioPin);
                Serial.print(" = ");
                Serial.println(state == 1 ? "ON" : "OFF");
            }
        }
    }
    else
    {
        Serial.print("A-HAP request failed. HTTP code: ");
        Serial.println(httpCode);
        setAllOutputsOff();
    }

    http.end();
}

void setup()
{
    Serial.begin(115200);
    delay(1000);

    for (int i = 0; i < OUTPUT_PIN_COUNT; i++)
    {
        pinMode(OUTPUT_PINS[i], OUTPUT);
    }

    setAllOutputsOff();
    connectToWiFi();
}

void loop()
{
    if (millis() - lastPollTime >= POLL_INTERVAL_MS)
    {
        lastPollTime = millis();
        pollAhapServer();
    }
}

9. Update the Sketch Before Uploading

Change these values before uploading the sketch:

10. Upload the Code

1. Connect the ESP32 using USB.
2. Open the sketch in Arduino IDE.
3. Select the correct ESP32 board.
4. Select the correct USB port.
5. Click Upload.
6. Open Tools > Serial Monitor.
7. Set the baud rate to 115200.

If everything is correct, the Serial Monitor should show the ESP32 connecting to Wi-Fi, then polling the A-HAP server.

11. Test Output Control

1. Open A-HAP in your browser.
2. Go to the Role you created for the ESP32.
3. Toggle the output ON and OFF.
4. The ESP32 should update the matching GPIO pin during the next polling cycle.

12. Troubleshooting