Smarthome Soldering Iron with Home Assistant and ESPHome (also: web GUIs for Pinecil)

March 28, 2023    Pinecil Home Assistant DIY RISC-V Blisp PineSAM Pine64 esphome

About a year ago, wesdottoday told me to buy a Pinecil and, once they came back in stock before the holidays.. I did just that… Fast forward a couple months and I’ve got a copr for flashing the Pinecil’s firmware (IronOS), and am spending my weekends playing around with Bluetooth Low Energy (BLE) and Home Assistant to automatically turn on my fan when I start tinkering at my desk, lest my lungs die from the fumes.

ESP-WROOM-32 Development MCU with a Pinecil v2 leaning on it

By popular demand, I’m writing a blog post about the Pinecil, how to flash the latest firmware, and then what you can (currently) do with bidirectional communication to your soldering iron.

We’ll also go over two Pinecil community projects offering in-browser experiences (PineSam and Joric’s ‘Pinecil’), and lastly some instructions on using an ESP32 and ESPHome to send Pinecil data to HomeAssistant so you can do everything from visualize your soldering statistics, to automatically turn on an exhaust fan when you start working.

Acknowledgements

  • Ben Brown (Ralim) - Maintainer and developer of IronOS for Pinecil and Miniware Irons
  • Gamiee (Gamelaster) - Developer and maintainer of pine64_updater, IronOS
  • River-Mochi for reviewing this article and their excellent organization and documentation work for Pine64 and the Pinecil.
  • TomW1605 & ithinkido for their work on the implementation of the Pinecil ESP32 integration
  • Builder555 - PineSAM maintainer and developer
  • Joric - Developer of original BLE GATT application for Pinecil

The Pinecil

The Pinecil is an open-source soldering iron based on the RISC-V architecture produced by Pine64. There are two versions of Pinecil - v1 and v2. Pinecil v1 does not have a Bluetooth Low Energy (BLE) chip, whereas Pinecil v2 does. In this blog post, we will focus on Pinecil v2. Pine64 does not distinguish between v1 and v2 except for on the PCB as a revision. If you’re buying a Pinecil in 2023 or beyond, and it’s from an official source, it is a v2.

You can find more information about the Pinecil in the links below, including where to buy. Check the Pinecil Wiki for up-to-date information on where to buy a genuine Pinecil, and how to avoid fakes.

  • Pine64.com - Offical store for Pine64 devices. Ships from China and takes 3-4 weeks for delivery
  • Pine64.org - The community associated with Pine64 devices. Check out the Discord/Telegram chat for a great group of tinkerers, and if you have any trouble with your Pinecil or associated tools
  • Pinecil Wiki - Lots of tips and tricks, as well as up to date purchasing and troubleshooting information.
    • Shout out to River-Mochi for their awesome work on keeping this up to date and useful
  • Pine64 Updater - v1 Pinecil updater tool
  • Pinecil Development Projects - Updated links to all community projects

Blisp

Blisp is a flashing tool used to flash ironOS on Pinecil v2 that stands for ‘Bouffalo Labs In-System Programming’. It’s used to flash the Bouffalo BL706 MCU that was integrated on the v2 Pinecil. You can find the source code for Blisp on GitHub.

I also maintain a Fedora COPR respository for it here, where you can find packages with precompiled binaries for Fedora and Enterprise Linux (8/9). I am working with Pine64 to make it easier to get it packaged for Fedora and other Linux distributions down the road.

Flashing the beta firmware with blisp

Until version v2.21 of IronOS ships, a beta firmware is required to use the BLE functionality of the Pinecil v2. There has been a significant amount of testing and development on the BLE stack on the main tree in the last few months and the developers have been making sure the BLE features are ready before they are released to a much larger audience.

Flashing the Pinecilv2 with blisp CLI

Once v2.21 is released, binaries can be retrieved from the IronOS Releases page.

Steps to download and flash

These steps assume you have a compiled version of blisp in your system path, either by installing from my COPR, or compiling on your own using the instructions in the repository.

  1. Find the latest sucessful actions run on the ironos repo here.
  2. Download the Pinecilv2 zip file for that run, and unzip it
  3. Plug your Pinecil into your computer while holding down the ‘Minus’ (-) button. The screen should not turn on. If on Linux, dmesg should report seeing the BL706 as a serial device.
  4. Run the following command to flash the firmware to your Pinecil:
    blisp write -c bl70x --reset /path/to/Pinecilv2_extracted/Pinecilv2_EN.bin
    
  5. Un-plug and plug the Pinecil back in to boot the new firmware

NOTE: You may ignore the .dfu and .hex files provided in the .zip file.

Pinecilv2 vs Pinecilv2_multi-lang

Two variants of firmwares for Pinecil are provided: combined mutli-language binaries, and individual per-language binaries. The per-language binaries are much smaller, and while the Pinecilv2 has more flash available to store the mutli-language images, for general usage, you will have an easier time with the language-specific binary rather than the multi-lang binaries.

Multi-lang provides three bundles of languages:

  1. Chinese and Japanese
  2. Russian, Ukranian, Serbian, and Bulgarian
  3. European (All not mentioned above)

Ultimately, it is up to you which you decide to use

Pineflash

Spagett1 updated their Pineflash tool which allows for a non-command-line experience for flashing new versions of IronOS on the Pinecil V1 and V2, similar to the Pine64 updater (add link) utility for the v1 Pinecil. You can find more information on the PineFlash GitHub repo. Feel free to check it out and give them feedback!

Pineflash supports Linux and MacOS at this time (2023-04-03), and support for Windows is a work in progress. If you would like to help test, please join the chat and make yourself known.

Bluetooth Low Energy

Bluetooth Low Energy (BLE) is a wireless communication protocol that is designed to consume less energy than classic Bluetooth. There is upcoming support in browser APIs to allow access to BLE devices, and so there are a handful of options for how to get your Pinecil talking to your computer.

Interacting with your Pinecil over Bluetooth

PineSAM by Builder555

PineSAM (Pinecil Settings and Menus) started out as an in-browser way to see and change settings. It’s served a multitude of uses from helping people with cracked or non-functional screens, all the way to adding really helpful accessibility features to those who struggle to read the small screen on the Pinecil. It’s is a Python and Vue-based application that has to have a server component running locally–along with a machine that has bluetooth. You can find the source code for PineSAM on GitHub, but read on below for how to grab precompiled versions of the application.

PineSAM UI

PineSAM allows the user to not only see the live temperature, wattage, and voltage of their device but change the settings and temperatures at a click. Uniquely, it allows users to set temperature presets for one-click changes between temperatures–for example to switch between leaded and unleaded solder.

You can access PineSAM from your mobile device once it’s running on your computer to have a touch-capable way of controlling your settings. On your phone, flip the screen to portait mode in order to see the graph as on desktop.

Screenshot of PineSAM UI on Mobile device

The PineSAM project is working to integrate a “Work” screen which takes inspiration from Joric’s UI. Due to this, it’s likely these two projects will end up combining into one, in my opinion, despite their distinct mechanisms for retrieving BLE data from the Pinecil.

Setting up PineSAM

See the project readme for the most up-to-date instructions. If you run into any trouble, come find us in the #pinecil channel on Pine64’s Discord or Telegram chat.

Joric’s BLE API

Another project is a more simple web UI that uses in-browser Bluetooth support (currently only really well supported in Chromium/Firefox, and even then it’s not universal or without bugs. This UI shows a nice graph of your Pinecil’s temperature and power supply information, but is limited to devices supporting WebBLE, and also is only able to change the set point (temperature) on the device. You can also find the source code for Joric UI on GitHub.

Joric's UI

Setting up Joric’s UI

No setup needed! Just browse to https://joric.github.io/pinecil/ in a compatible browser. I’ve personally tested Firefox and Chromium on Fedora 37, but I know others have got it working on Windows and MacOS, too.

As with PineSAM, feel free to come to chat for help and support.

Home Assistant Setup with ESPHome

If Home Assistant (HASS) is more your speed, read on below. Be warned to get this setup, you will need some sort of ESP32 device to read data from your Pinecil and report it to Home Assistant. I used one of the WROOM ESP32 dev boards I’ve had in my closet for a few months (not an affiliate link).

If you’re not familiar, Home Assistant is an open-source home automation platform which can inte grate with ESPHome, another open source system to control your ESP8266/ESP32 using just YAML configurations. In this section, I’ll walk though how to setup an ESP32 with will show you how to create a smart soldering iron using Pinecil with Home Assistant and ESPHome.

Home Assistant Soldering UI

To make this work, we’ll use an ESPHome configuration file put together by Pine64 community member TomW1605. Thank you again, Tom!

Requirements

Steps

  1. Login to ESPHome
  2. Import this ESPHome configuration file.
  3. Modify and set up the configuration file as follows:
    1. Change board in esp32 section to your board.
      • If using the WROOM 32 I linked above, use nodemcu-32s
    2. Setup an encryption key. This must be a base64-encoded, 32 bit string.
      • You can create one on the CLI using openssl rand -base64 32
    3. Change OTA password to desired
    4. Change wifi SSID and password for your network in ESPHome secrets
    5. Change wifi access point fallback settings to desired
    6. Important - Change ble_client mac address to your Pinecil’s MAC. This can be found in the settings as well as in logs from the above tools (Joric/PineSAM)
      Pinecil esp32 configuration example
  4. Flash the firmware to the ESP32 device
  5. Add the device to Home Assistant
  6. Create a Home Assistant dashboard to control and monitor your smart soldering iron.

Now that you’ve got that setup, you should start to see data coming in about your Pinecil’s settings! Go on and automate thy solder.