Connecting Emerald Electricity Advisor to ESPHome via BLE
I'm making this post to hopefully help anyone in the future that is trying to connect their emerald advisor to Home Assistant. As I had ran into a few issues that made it harder than I thought it was going to be. I troubleshooted this using gemini AI and I've written a summary of what I did to finally get it working. If you come across this thread and can't get it to work still, reply or send me a message I'd be happy to try and help.
If you are trying to connect an Emerald Electricity Advisor (EIAdv) directly to Home Assistant using ESPHome and are running into Status 133 connection timeouts, GATT errors, or compilation issues with external components, here is the working solution and complete setup guide.
1. Local Custom Component Setup (emerald_ble.cpp)
I used the code from whitty's emerlad_ble fork on github, which is a fork from emerald electricity advisor by WeekendWarrior1.
I had to make some modification to the cpp file though so I downloaded the files from whitty's github page and saved them locally on my home assistant server so I could edit them.
-
In Home Assistant, open your file manager (Studio Code Server, File Editor, or Samba).
-
Go to your ESPHome directory:
/config/esphome/. -
Create the directory path:
/config/esphome/my_components/emerald_ble/. -
Save the following code as
emerald_ble.cppinside/config/esphome/my_components/emerald_ble/:#include "emerald_ble.h" #include "esphome/core/log.h" #include "esphome/core/hal.h" #include "esphome/core/time.h"
#ifdef USE_ESP32
namespace esphome { namespace emerald_ble {
static const char *const TAG = "emerald_ble";
void Emerald::dump_config() { ESP_LOGCONFIG(TAG, "EMERALD"); LOG_SENSOR(" ", "Battery", this->battery_); LOG_SENSOR(" ", "Power", this->power_sensor_); LOG_SENSOR(" ", "Daily Energy", this->daily_energy_sensor_); LOG_SENSOR(" ", "Total Energy", this->energy_sensor_); ESP_LOGD(TAG, "pulses_per_kwh_: %f", this->pulses_per_kwh_); ESP_LOGD(TAG, "pulse_multiplier_: %f", this->pulse_multiplier_); }
// void Emerald::setup() { this->authenticated_ = false; }
std::string Emerald::pkt_to_hex_(const uint8_t *data, uint16_t len) { char buf[64]; memset(buf, 0, 64); for (int i = 0; i < len; i++) sprintf(&buf[i * 2], "%02x", data[i]); std::string ret = buf; return ret; }
void Emerald::decode_(const uint8_t *data, uint16_t length) { ESP_LOGD(TAG, "DEC(%d): 0x%s", length, this->pkt_to_hex_(data, length).c_str()); }
void Emerald::parse_battery_(const uint8_t *data, uint16_t length) { ESP_LOGD(TAG, "Battery: DEC(%d): 0x%s", length, this->pkt_to_hex_(data, length).c_str()); if (length == 1) { this->battery_->publish_state(data[0]); } }
uint32_t Emerald::parse_command_header_(const uint8_t data) { uint32_t command_header = 0; for (int i = 0; i < 5; i++) { command_header += (data[i] << (8(4-i))); } return command_header; }
uint32_t Emerald::decode_emerald_date_(const uint8_t data) { uint32_t command_date_bin = 0; for (int i = 5; i < 9; i++) { command_date_bin += (data[i] << (8(8-i))); } return command_date_bin; }
void Emerald::decode_emerald_packet_(const uint8_t *data, uint16_t length) { ESP_LOGD(TAG, "DEC(%d): 0x%s", length, this->pkt_to_hex_(data, length).c_str()); if (length >= 5) { uint32_t command_header = this->parse_command_header_(data); switch(command_header) { case RETURN30S_POWER_CONSUMPTION_CMD: { if (length != 11) { //return }
uint16_t pulses_within_interval = data[9] << 8; pulses_within_interval += data[10]; float avg_watts_within_interval = pulses_within_interval * this->pulse_multiplier_; ESP_LOGI(TAG, "Timestamp: , Pulses: %d, Average Watts within interval: %f W", pulses_within_interval, avg_watts_within_interval); if (this->power_sensor_ != nullptr) { this->power_sensor_->publish_state(avg_watts_within_interval); } if (this->energy_sensor_ != nullptr) { total_pulses_ += pulses_within_interval; float energy = total_pulses_ / this->pulses_per_kwh_; this->energy_sensor_->publish_state(energy); } if (this->daily_energy_sensor_ != nullptr) { this->daily_pulses_ += pulses_within_interval; float energy = this->daily_pulses_ / this->pulses_per_kwh_; this->daily_energy_sensor_->publish_state(energy);#ifdef USE_TIME auto *time_ = *this->time_; ESPTime date_of_measurement = time_->now(); if (date_of_measurement.is_valid()) { if (this->day_of_last_measurement_ == 0) { this->day_of_last_measurement_ = date_of_measurement.day_of_year; } else if (this->day_of_last_measurement_ != date_of_measurement.day_of_year) { this->daily_pulses_ = 0; this->day_of_last_measurement_ = date_of_measurement.day_of_year; } } else { #else uint32_t command_date_bin = this->decode_emerald_date_(data); uint8_t day_of_measurement = ((command_date_bin >> 17) & 0b11111); // 1-31 if (this->day_of_last_measurement_ == 0) { this->day_of_last_measurement_ = day_of_measurement; } else if (this->day_of_last_measurement_ != day_of_measurement) { this->daily_pulses_ = 0; this->day_of_last_measurement_ = day_of_measurement; } #endif #ifdef USE_TIME } #endif }
break; } case RETURN_UPDATED_POWER_CMD: { break; } case RETURN_EVERY30S_POWER_CONSUMPTION_CMD: { break; } case RETURN_IMPULSE_CMD: { break; } case RETURN_PAIRING_CODE_CMD: { break; } case RETURN_DEVICE_TIME_CMD: { break; } }} else { // failure log } }
void Emerald::gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if, esp_ble_gattc_cb_param_t *param) { switch (event) { case ESP_GATTC_DISCONNECT_EVT: { break; } case ESP_GATTC_SEARCH_CMPL_EVT: { break; } case ESP_GATTC_READ_CHAR_EVT: { ESP_LOGD(TAG, "[%s] ESP_GATTC_READ_CHAR_EVT (Received READ)", this->parent_->address_str()); if (param->read.status != ESP_GATT_OK) { ESP_LOGW(TAG, "Error reading char at handle %d, status=%d", param->read.handle, param->read.status); break; }
if (param->read.handle == this->time_read_char_handle_) { ESP_LOGD(TAG, "Recieved time read event"); this->decode_emerald_packet_(param->read.value, param->read.value_len); break; } break; } case ESP_GATTC_WRITE_CHAR_EVT: { ESP_LOGD(TAG, "[%s] ESP_GATTC_WRITE_CHAR_EVT (Write confirmed)", this->parent_->address_str()); if (param->write.status != ESP_GATT_OK) { ESP_LOGW(TAG, "Error writing value to char at handle %d, status=%d", param->write.handle, param->write.status); break; } break; } case ESP_GATTC_NOTIFY_EVT: { ESP_LOGD(TAG, "[%s] Received Notification", this->parent_->address_str()); if (param->notify.handle == this->time_read_char_handle_) { ESP_LOGD(TAG, "Recieved time read notification"); this->decode_emerald_packet_(param->notify.value, param->notify.value_len); break; } if (param->notify.handle == this->battery_char_handle_) { ESP_LOGD(TAG, "Recieved battery notify event"); this->parse_battery_(param->notify.value, param->notify.value_len); break; } break; } default: break;} }
void Emerald::gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) { switch (event) { case ESP_GAP_BLE_AUTH_CMPL_EVT: { if (param->ble_security.auth_cmpl.success) { auto status = esp_ble_gattc_register_for_notify(this->parent_->get_gattc_if(), this->parent_->get_remote_bda(), this->time_read_char_handle_); if (status) { ESP_LOGW(TAG, "[%s] esp_ble_gattc_register_for_notify failed, status=%d", this->parent_->address_str(), status); }
ESP_LOGI(TAG, "[%s] Writing auto upload code to Emerald", this->parent_->address_str()); auto write_status = esp_ble_gattc_write_char(this->parent()->get_gattc_if(), this->parent()->get_conn_id(), this->time_write_size_char_handle_, sizeof(setAutoUploadStatusCmd), setAutoUploadStatusCmd, ESP_GATT_WRITE_TYPE_NO_RSP, ESP_GATT_AUTH_REQ_NONE); if (write_status) { ESP_LOGW(TAG, "Error sending write request for pairing_code, status=%d", write_status); } // read battery auto read_battery_status = esp_ble_gattc_read_char(this->parent()->get_gattc_if(), this->parent()->get_conn_id(), this->battery_char_handle_, ESP_GATT_AUTH_REQ_NONE); if (read_battery_status) { ESP_LOGW(TAG, "Error sending read request for battery, status=%d", read_battery_status); } // Enable notifications for battery auto notify_battery_status = esp_ble_gattc_register_for_notify( this->parent_->get_gattc_if(), this->parent_->get_remote_bda(), this->battery_char_handle_); if (notify_battery_status) { ESP_LOGW(TAG, "[%s] esp_ble_gattc_register_for_notify failed, status=%d", this->parent_->address_str(), notify_battery_status); } } break; } case ESP_GAP_BLE_PASSKEY_REQ_EVT: { ESP_LOGE(TAG, "ESP_GAP_BLE_PASSKEY_REQ_EVT, onPassKeyRequest %x", event); esp_ble_passkey_reply(param->ble_security.ble_req.bd_addr, true, this->pairing_code_); break; } default: break;} }
} // namespace emerald_ble } // namespace esphome
#endif
2. Unpair Phone & Hard Reset the Advisor
The Emerald Advisor will refuse connection requests from the ESP32 if it is still actively bonded or connected to another phone.
- Remove Device from App: Open the Emerald App on your phone and delete/remove the Advisor.
- Forget Bluetooth Device: Go into your phone’s system Bluetooth settings, find the Emerald Advisor, and select Forget / Unpair.
- Turn Off Phone Bluetooth: Turn off Bluetooth on your phone so it doesn't attempt to re-pair in the background.
- Hard Reset the Unit:
- Locate the pinhole reset button on the Emerald Advisor.
- Using a pin, press and hold the reset button for 15 seconds.
- Release, wait a few seconds, then press and hold it again for 3 seconds.
- (Note: The Emerald unit does not have an indicator LED. Even though it gives no feedback, this sequence resets its internal bonding state so it accepts new pairing keys).
- Working ESPHome YAML Configuration
Key settings required:
-
ESP-IDF Framework: Stable memory allocation for BLE coexistence (
sram1_as_iram: true). -
IO Capabilities: Set
io_capability: keyboard_displayto satisfy the passkey authentication requirements during GATT security exchange. -
Scan Parameters:
interval: 320ms/window: 320msfor 100% duty cycle scanning so advertisement packets aren't missed. -
Local Component: Points directly to
path: my_components.esphome: name: emerald-advisor friendly_name: Emerald Advisor Reader
esp32: board: esp32dev variant: ESP32 framework: type: esp-idf advanced: minimum_chip_revision: "3.0" sram1_as_iram: true
logger: level: DEBUG
api: encryption: key: !secret emerald_advisor__encryption_key
ota: - platform: esphome
wifi: ssid: "YOUR_WIFI_SSID" password: "YOUR_WIFI_PASSWORD" power_save_mode: NONE ap: ssid: "Emerald-Advisor-Fallback" password: ""
captive_portal:
Direct local component path import
external_components: - source: type: local path: my_components components: [ emerald_ble ]
time: - platform: homeassistant id: homeassistant_time
esp32_ble: io_capability: keyboard_display
esp32_ble_tracker: scan_parameters: interval: 320ms window: 320ms active: true
ble_client: - mac_address: "30:1B:97:6B:A4:A2" # Replace with your Advisor MAC Address id: emerald_advisor
sensor: - platform: emerald_ble ble_client_id: emerald_advisor power: name: "Current Power Demand" unit_of_measurement: "W" device_class: power state_class: measurement daily_energy: name: "Daily Energy Consumption" unit_of_measurement: "kWh" device_class: energy state_class: total_increasing energy: name: "Total Energy Consumption" unit_of_measurement: "kWh" device_class: energy state_class: total_increasing battery_level: name: "Advisor Battery Level" unit_of_measurement: "%" device_class: battery entity_category: diagnostic
# DEVICE SPECIFIC VALUES pairing_code: 018685 # Replace with the 6-digit PIN on the device sticker pulses_per_kwh: 3200 # Match your meter's imp/kWh rate (e.g. 1000, 3200) time_id: homeassistant_time
Errors that I ran into that I'll include below so if someone googles them they might find this post
- BLE Connection & Disconnect Errors
1. BLE Connection & Disconnect Errors
Status 133/GATT_ERROR (0x85)- Log symptom:
[W][ble_client:xxx]: Connection failed with status 133or repeated[W][esp32_ble_tracker:xxx]: Connection timed out. - Cause: The ESP32’s BLE stack failing to establish or maintain a stable GATT connection using the default Arduino framework or default scan parameters.
- Fix: Switch the ESP32 framework to
esp-idf, addsram1_as_iram: true, and adjust scan parameters tointerval: 320ms/window: 320ms.
- Log symptom:
2. Authentication & Bonding Failures
Reason 81/BLE_HS_EDONE(Authentication / Bond Failure)- Log symptom:
[W][ble_client:xxx]: Disconnected: reason=81or pairing handshake failing repeatedly during passkey exchange. - Cause: The Emerald Advisor was still bonded to your smartphone or holding active session memory, preventing the ESP32 from establishing a new encrypted relationship.
- Fix: Unpair from the phone app, turn off phone Bluetooth entirely, perform a 15-second hard pin reset on the Emerald unit, and add
esp32_ble: io_capability: keyboard_displayto ESPHome. - auth fail reason=81
- Log symptom:
3. Build & Compilation Errors
- C++ Namespace / Scope Errors in
emerald_ble.cpp- Log symptom:
error: ‘emerald_ble’ has not been declaredor compiler errors regarding missing class definitions / API type mismatches. - Cause: Version mismatches between the ESPHome API headers and the external component source code.
- Fix: Manually patch
emerald_ble.cpp/ component headers locally to align namespace definitions with your active ESPHome release.
- Log symptom:
Posted Aug 2, 2026, 7:05 AM UTC