Napoleon eFIRE-enabled Fireplaces (Work in Progress)

FelixKa · March 15, 2023, 4:08am

Hey there,

I’ve started working on integrating my Napoleon gas fireplace into Home Assisstant using the eFIRE Bluetooth controller it has.

A first version for testing has been released as a Custom Component:
Installation Instructions here: Napoleon eFIRE Custom Component Installation

Screenshot

Reverse Engineering the damn thing

To get here I had to reverse engineer the Bluetooth protocol the fireplace uses to communicate with the eFIRE App. That work is complete and can be viewed here: eFIRE Bluetooth Protocol - Bonaparte 0.1.0 documentation

I then went ahead and turned this information into a Python library, so that it can be used with Home Assistant. Much credit goes to @bdraco whose BLE libraries I have used as templates for this.

There is some other cool stuff I found out in the process which suggests I could ultimately build an ESPHome device to speak directly to the ProFlame 2 IFC in my fireplace, getting rid of the Bluetooth module. Check out my other part of the reverse engineering journey: System Information - Bonaparte 0.1.0 documentation

Limitations

RF remote disables Bluetooth Control

As soon as you use the RF remote to control the fireplace all bets are off.
At least in my instance the eFIRE controller doesn’t register that happening and it will lose all ability to correctly report state and control the fireplace. This is a limitation of the IFC, not the Bluetooth module. The eFIRE App is supposed to display an overlay in this case preventing you from using the app further. But for me this doesn’t work.

If you turn on the fireplace using the RF remote or override control using the RF remote you will be subsequently unable to see or control the state in HA. This means you can also not turn off a fireplace in HA that was turned on using the RF remote. So it’s probably best to discontinue use of the RF remote altogether when using this integration.
The good news is that the integration is way snappier than the RF remote for me. Especially since I can immediately turn on the fireplace to its lowest setting, which is my preferred setting. The remote turns it on full blast and then I have to press the “down” button five times and wait for the fireplace to acknowledge the command.

RF remote overrides state

State is pretty absolute on this IFC. That means with every change the entire state is written to the IFC (and thus overwritten).
Since RF remote and Bluetooth are mutually exclusive they cannot sync state with each other.
The only time where this is annoying is when you set any of the features that you’d like to stick for an extended amount of time and across control modes (e.g. AUX relay, Continuous Pilot)
In my case it is the Continuous Pilot setting. I like to turn it on in winter and have it stay on for the season. Setting this setting through Bluetooth is possible, but unless you also set it to on in your RF remote it will always be returned to off when you use the remote.

Implementation status

Fireplace On / Off as Switch entity (synced with Flame Height)
Flame Height Number entity with Slider
Night Light as dimmable Light entity
Blower as Fan entity with 6 speeds
Continuous Pilot as Switch entity
Aux Relay as Switch entity
Split Flow as Switch entity (untested, don’t have this feature)
External LED controller as RGB Light entity with effects (don’t have this feature)
Sleep timer (likely not going to implement, use Automations in Home Assistant instead)

Next steps

Publish Bluetooth Library on GitHub: GitHub - kaechele/bonaparte: Library to control Napoleon eFIRE enabled fireplaces
Publish Bluetooth Library on PyPI: pybonaparte · PyPI (Possibly pending rename to bonaparte, see PEP 541 Request: bonaparte · Issue #2683 · pypi/support · GitHub)
Publish HA custom component to GitHub / HACS: GitHub - kaechele/napoleon-efire: Napoleon eFIRE Integration for Home Assisstant
Community Testing
Pull request for core integration

Looking for

People to

express their interest in this integration
test the integration using the custom component
review the library code and suggest improvements
review the documentation and suggest improvements

stvsu · July 13, 2023, 6:27pm

Ok my fireplace insert was installed today. Using the eFire app, I have access to:

On/Off
Flame Height
Blower On/Off
Blower Speed (Slider)
Night Light On/Off
Night Light (Slider)
Split Flow (On/Off)
Continuous Pilot (On/Off)
Off Timer

I am extremely interested in this integration. I would love to test this out.

Are you still interested in working on this? Happy to help any way I can. My HA NUC has Bluetooth and is near the fireplace, so I should be able to integrate pretty easily.

I’m less technical, so I’m not sure I can test until there is a HA custom component on GitHub or HACS. Happy to help in any way I can!

EDIT: If there’s a walkthrough on how I can run the GH repo on my HA machine and integrate into HA I’m sure I can pull that off. Any resources you can point me to? Familiar with linux/git commands and generally running code and servers, but can’t write code.

bdraco · July 13, 2023, 6:43pm

I would pick a new name. The PEP541 requests rarely get answered (or at least not quickly)

FelixKa · July 14, 2023, 12:39am

Happy that there is more interest in this integration.
As for the Bluetooth based integration:
I put it on the back burner a bit due to other things going on but it’s pretty much 85-90% done. It all pretty much works but still is largely untested and needs a bit of cleanup. My plan was to make it available as a custom_component for initial testing and then submit it to HA core according to the procedure there.

I have also been active on the RF remote and IFC UART side of the equation.

The only benefit of UART direct to the IFC (essentially replacing the Bluetooth module with, for example, an ESP32 with ESPHome) is that you can get rid of Bluetooth as a point of failure. The annoying bit is that the IFC provides 3.3V power but ESP32s need 5V input voltage. So you’d need to bring 5V to your fireplace somehow.

The RF Remote is the safest bet as it gets to override whatever comes in over UART. On that end we’re still not quite at the point where we can generate valid checksums for arbitrary packets (work is ongoing here: Proflame 2 support · Issue #1905 · merbanan/rtl_433 · GitHub).
The RF remote is transmit only, so it would not notice if another RF module changes settings. The way the remote works is that it always sends the entire state of the IFC with every command it sends. So it’d overwrite whatever settings were changed through a 3rd party RF module that copied the remote’s serial number, even if the change made on the remote is unrelated to the change made through the 3rd party module
As an example:

turn on fireplace with the RF remote
turn on lights through the ESPHome module (the RF remote will not know it happened)
use the remote to change flame height from 6 to 5

The change on the fireplace in 3. (due to the RF packets always transmitting the entire state) would be: the lights would turn off and the flame height is decreased to 5.

The ESPHome module on the other hand can include an RF receiver together with the transmitter and listen for communications from the OEM remote and therefor track the state the remote sets. I do have a working encoder for ESPHome’s remote_receiver component. Work on the remote_transmitter portion has stalled due to the aforementioned checksum problem.

I think the sweet spot for Bluetooth module replacement would be ESPHome talking UART to the IFC and having an RF Receiver to receive commands from the OEM remote and pass those on to the IFC via UART. With that the ESPHome module would not need an RF Transmitter. The RF Receiver on the fireplace can be turned off so as to not interfere with the UART operations.

Side note: Something that just came to my mind is an ESPHome RF proxy, the same way we now have ESPHome BLE proxies. Interesting thought

bdraco · July 14, 2023, 1:42am

There are a lot of ESP32 options that have both a Vin 3.3v and 5v pin

I’m using the below one for a similar application:

https://www.amazon.com/gp/product/B08L79192D/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8&th=1

bdraco · July 14, 2023, 9:31pm

Bluetooth should be very reliable if you have two Bluetooth proxies since if anything fails it will switch over. If you have a custom component in a state that it can make a connection and send/read a command but needs cleanup, I’m happy to give it a try and send you a few PRs to clean it up.

Feel free to reach out on discord.

Cheers

stvsu · July 14, 2023, 10:58pm

@FelixKa please let me when it’s available as a custom_component and I will be a happy beta tester.

Personally I would probably opt for using the BT version, rather than replacing the hardware on the device itself, as I know myself (and potentially others) may be hesitant to alter the device/void warranty.

Love the work that’s going into this!

c_slip · August 12, 2023, 5:05pm

I am definitely interested in being a beta tester when this is available as a custom_component. I would also opt for the BT version as it is perfect already having a ESP32 BT Proxy within range.

FelixKa · August 12, 2023, 5:27pm

Great to hear!
I’m about 85% there. I have meanwhile

published the library to PyPI under a different name than what I initially planned (pybonaparte · PyPI) to speed things up a bit
created the GitHub repo for the custom_integration (not much to see there yet)
cleaned up most of the code locally and put it in the correct structure to be a custom_component

Left to do is:

test locally
add Napoleon brand to GitHub - home-assistant/brands: 🎨 Brands for Home Assistant
push code to above mentioned GitHub for anyone interested to try

I’m a bit busier with other stuff than I anticipated but we’re getting there

FelixKa · August 27, 2023, 6:13am

Alright, a first version for testing is out. Just in time before fireplace season is upon us

See the README.md in the repository for how to add the repo to HACS: GitHub - kaechele/napoleon-efire: Napoleon eFIRE Integration for Home Assisstant

I tested it locally for a bit and it seemed to work OK. There is a bit of a delay on some commands but I think I can work that out given more testing.

A PR to add the logos is underway here: Add Napoleon brand for Napoleon eFIRE custom integration by kaechele · Pull Request #4618 · home-assistant/brands · GitHub

bdraco · August 27, 2023, 2:36pm

I looked though the code and it looks nice and clean so getting it merged to core shouldn’t be too much work.

It found mine right away. I haven’t had a chance to test it beyond getting it set up.

Note: the screenshot was taken before the brand logos were merged

FelixKa · August 27, 2023, 3:13pm

Nice! Happy it was able to detect your fireplace right away.

I think most improvement to the performance could be made within my bonaparte library for the Bluetooth communication. I’m not sure I’m using locking/batching/debouncing correctly.

For me right now the most obvious effect is trying to turn on the night light and then immediately turning it off: The switch will flip to the off position, immediately revert back to on and then take about 2-3 seconds to revert back to off when the Bluetooth controller reports back the updated state.

Also interesting to see that your BLE firmware is v11. Mine is v8 (fireplace installed in 2019). I’m hoping that the newer version actually implements the feature to report back when use of the RF remote is blocking the Bluetooth controller from making any changes to the fireplace state. This feature is, in fact, implemented in the Napoleon eFIRE app but doesn’t work with my fireplace.
It is detectable on the IFC’s serial port (which the Bluetooth controller uses) that a command is unsuccessful due to RF remote use. Specifically, the Bluetooth controller will send a command to request access to make changes to state and the IFC will respond with an error. That works even on my fireplace, the Bluetooth controller doesn’t seem to use this information though as the Bluetooth command that is supposedly used to query this doesn’t yield any response on my fireplace.
I’ve documented all this on in the docs for the bonaparte library: System Information - Bonaparte 0.1.0 documentation

I will put together some test scripts for people to run on their fireplaces to figure this out.

EDIT: Commands are at least somewhat fast and most times any actions feel pretty instant. On average I see about 500ms round trip for any given command/response cycle.

stvsu · September 4, 2023, 11:28pm

Just added the custom component through HACS. When adding Napoleon eFire through Settings → Devices & Services → Add Integration → Napoleon eFire, I’m getting this box with nothing in it.

Any idea how to proceed?

stvsu · September 4, 2023, 11:43pm

Got it working. I needed to add the Bluetooth integration first.

This is incredible - works perfectly, and significantly better than the native “eFire” app on my iPhone.

Wow wow wow, going to be a fun winter

FelixKa · September 4, 2023, 11:56pm

Thanks for testing! Glad it’s working for you!

Yes, the empty box will show up when there are no fireplaces detected on the Bluetooth side.

I’ll see if I can put a message there that no devices were found.

Now to see if it holds up long term

stvsu · September 5, 2023, 12:47am

Hmm, was working for a bit, but now isn’t.

Let me know if it makes more sense to move this to GH issues.

Seeing this error pop up in system logs, and the device now says “Failed to set up”

Logger: homeassistant.config_entries
Source: custom_components/napoleon_efire/__init__.py:71
Integration: Napoleon eFIRE (documentation, issues)
First occurred: 5:45:37 PM (1 occurrences)
Last logged: 5:45:37 PM

Error setting up entry NAP_FPC_0A3C for napoleon_efire
Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/config_entries.py", line 388, in async_setup
    result = await component.async_setup_entry(hass, self)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/config/custom_components/napoleon_efire/__init__.py", line 71, in async_setup_entry
    if not await fireplace.authenticate(password):
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/bonaparte/fireplace.py", line 223, in authenticate
    response = await self.execute_command(
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/bonaparte/device.py", line 387, in execute_command
    response = await self._execute(message)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/bonaparte/device.py", line 351, in _execute
    return await self._execute_locked(message)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/bleak_retry_connector/__init__.py", line 471, in _async_wrap_bluetooth_connection_error_retry
    return await func(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/bonaparte/device.py", line 305, in _execute_locked
    result = await future
             ^^^^^^^^^^^^
asyncio.exceptions.CancelledError: aiohttp connection lost

EDIT: And it’s working again. I’ll play around with it for the next couple days and see if it continues losing connection.

Looking great so far!

FelixKa · September 5, 2023, 1:50am

Looks like the underlying library lost connection and had to reauthenticate. That’s the type of scenario I was anticipating but I haven’t gathered enough data on yet.
There is some wiggle room as to how we interact with the fireplace (keep a connection open or reconnect/reauthenticate for any commands). Right now it does a bit of a hybrid between the two.

stvsu · September 5, 2023, 2:05am

Makes sense, I realize those logs dont say much, so let me know if theres a better way to debug if useful for your implementation.

Now I’m just trying to figure out how to add a slider for the blower speeds!

FelixKa · September 7, 2023, 9:21pm

You could use the new Tile Card features and add “Fan speed” as a feature. It will show up as a slider.

stvsu · September 8, 2023, 5:52pm

Ended up using the custom slider entity row. Looking great! And the integration seems to be working flawlessly