The house I recently moved into contains 40+ 6" recessed lights all containing incandescent or halogen bulbs ranging from 120 to 150 watts each. Basically they had flood lights installed in the house. These lights were all extremely bright and completely inefficient. I am in the process of replacing all of them with these Hue Downlights, which are only 9 watts each, and plenty bright at 650 lumens. On top of that I can now control the color or temperature of every light in the house.

In my previous house I controlled Hue lighting from Indigo and used physical Insteon dimmers. I want to achieve the same thing in the new house, but using Home Assistant. I feel like I caused myself a bit of headache by wanting to use the Insteon dimmers, because they have lights on them that show the brightness level., and I am not able to handle this light not properly reflecting the brightness of the Hue bulbs being controlled. I also wanted to be able to make them be able to dim or brighten the hue bulbs by holding down the dimmer paddle like intended with standard bulbs.

Whats been done so far?

I’ve successfully got the Insteon dimmers setup and working with Home Assistant using Insteon-MQTT running in a Docker container. I’m able to control the dimmers through the Home Assistant UI and see their state reflected by interacting with them manually. You can read about how I set this part up here:

Setup Insteon-MQTT and integrate with Home Assistant

Time to actually control something!

My first attempt at making all of this work was by using normal HA automations written in YAML. In the beginning it seemed like this was going to work without any issue. Turning the lights on and off was extremely straight forward. 15 minutes later if thats all I wanted I would have been done.

Why it got complicated

The Insteon Dimmers when brightening or dimming only send payloads of in UP, DOWN, and STOP. They do not know their actual brightness level, and only report that level after they send STOP. If I actually wanted to change the brightness I needed to kick off a script that would increase or decrease the brightness at an interval until the STOP payload was received. This seemed easy enough, and I did get that working as well. There is even an example of it in the Home Assistant docs. This is now the point where I'm my own worst enemy and everything fell apart. After the STOP payload came through I'd stop the script, and then the dimmer would report its brightness and since I was changing the light brightness independently of the dimmer brightness things would be out of sync and the light would either brighten or dim to match the dimmer itself. I got it pretty close by adjusting the timing and amount the brightness changed each loop, but it was never quite right. Here's an example of just the yaml file for brightness changing from the dimmer.

- id: dimmer_brightness
  alias: "Dimmer Brightness Change"
  trigger:
    platform: state
    entity_id:
      - light.dimmer
  condition:
    condition: template
    value_template: >-
      {% set manual_state = state_attr(trigger.entity_id, "manual_state") %}
      {% set is_not_manual = (manual_state == "STOP" or manual_state == "None") %}
      {% set dimmer_on = (trigger.from_state.state == 'on' and trigger.to_state.state == 'on') %}
      {% set from_off_to_on = trigger.from_state.state == 'off' and trigger.to_state.state == 'on' %}
      {% set brightness_change = trigger.from_state.attributes.brightness != trigger.to_state.attributes.brightness %}
      {% set needs_update = state_attr(state_attr("sensor.insteon_map", state_attr(trigger.entity_id, 'address')), 'brightness') != trigger.to_state.attributes.brightness %}
      {{ dimmer_on and brightness_change and is_not_manual and needs_update  }}
  action:
    - service: light.turn_on
      data_template:
        entity_id: >-
          {% set address = state_attr(trigger.entity_id, 'address') %}
          {{ state_attr("sensor.insteon_map", address) }}
        brightness: >-
           {{ trigger.to_state.attributes.brightness }}

Does that explain why I felt it got too complicated? I needed to check all sorts of different conditions and try to present that in a sane way through yaml. I started to go slightly crazy. In the end I had 9 yaml files with the different parts of the automations to keep everything in sync.

What were my options?

I’m sure there are plenty of options, but the two I looked into were Node Red and AppDaemon. My initial instinct was to try and use AppDaemon since I’m relatively comfy writing Python, and it’s a familiar path to have to take from my experiences using Indigo. I ended up deciding to give Node Red a try first though, since the barrier to entry as well as the visual representation was appealing and seemed like it might be easier to manage later once I’ve forgotten how everything works at a later date.

So, I Installed and Setup Node Red

Installing Node Red in Docker for Home Assistant

Adding the Dimmers to HA

The dimmers are added pretty much as you’d expect based on how I walked through setting up insteon-mqtt with home assistant. There are a few differences though, which are the addition of json_attributes_topic which is going to be how we are able to track the manual interactions, as well as the addition of a unique_id for no reason other than I didn't like the UI complaining to me about it not having one.

- name: dimmer_hallway
  platform: mqtt
  schema: json
  state_topic: "insteon/41.b3.5e/state"
  command_topic: "insteon/41.b3.5e/level"
  json_attributes_topic: "insteon/41.b3.5e/manual_state"
  brightness: true
  unique_id: 41.b3.5e

There will be an additional attribute that will show up called manual_state which will say STOP once you've released the dimmer paddle.

Creating a Generic HA Config and Node Red Flow

My goal was to make it so that for 99% of the use cases I would be able to simply add a new hue bulb and “pair” it to a dimmer switch and have it work with little effort. To do that I ended up with the concept of sync_entity_id, sync_address, address, sync_entites, sync_dimmers, and sync_bulbs.

There very well may be a much more straight forward way of doing it but I found myself in the situation where I needed a place to store some additional meta data that was manually configured for my lights and dimmers. To do this I heavily utilized the flexibility of customize.yaml.

#----------------------------------------------------------
#         Hallway Dimmers
#----------------------------------------------------------
light.dimmer_hallway:
  address: 41.b3.5e
  is_sync_dimmer: true
  sync_entity_id: light.hallway
  friendly_name: Hallway Dimmer

light.dimmer_hallway_master:
  address: 41.b8.f6
  is_sync_dimmer: true
  sync_entity_id: light.hallway
  friendly_name: Hallway Dimmer Master

#----------------------------------------------------------
#          Hallway Bulbs
#----------------------------------------------------------
light.hallway:
  sync_address: 41.b3.5e
  is_sync_bulb: true
  sync_entities:
    - light.dimmer_hallway
    - light.dimmer_hallway_master

What are these used for?

These probably wont make a ton of sense at the moment but will be more clear once we get into the Node Red flow.

Dimmers

• address — the actual insteon device address
• is_sync_dimmer — so we know if the dimmer is supposed to talk to a bulb
• sync_entity_id: id of the bulb to reference

Bulbs

• sync_address — the address of the insteon device to control
• is_sync_bulb — so we know if the bulb is supposed to talk to a dimmer
• sync_entities — list of dimmers to update when the light changes

Creating the Flows

Now that the Home Assistant configuration is handled its time to create the flow. The main thing to remember here is that the state of the bulb is always the most important truth. By taking this approach we wont end up in any weird update loops and also still have the ability to use any third party apps to control the bulbs and the dimmers will still respond appropriately. You can download the Entire Node Red Flow otherwise I’ve broken it up into chunks that are linked to as we go.

Bulb Flow

Here’s what the flow for the lights changing looks like, and you can download it here: light-flow.json

The first thing that happens is we check if the bulb is a sync_bulb, and if it is we move on to a function node which gets the list of sync_entities so that we can update their state.

let attrs = msg.data.new_state.attributes;
let payload = msg.payload;

if(attrs.hasOwnProperty("sync_entities")) {
    msg.payload = attrs.sync_entities;
    msg.original_payload = payload;
    return msg;
}

Next those entities are piped through the split node, so that we can go get each dimmer individually using its it. The split node sends an individual msg for each entity_id in the sync_entities list. It sets msg.payload to each of those entity_ids, which go through a ha-get-entities node that uses the entity_id as its property its searching on.

Finally there is a check using a switch node that looks at the original payload to see if the bulb was turning on or off. From there if its off we turn the dimmer off, and if its on there is one last check to make sure the bulb wasn’t changing state due to a manual interaction with the dimmer.

let attrs = msg.payload.attributes;
let hasManual = attrs.hasOwnProperty("manual_state");

if(!hasManual || hasManual && attrs.manual_state == "STOP") {
    return msg;
}

Dimmer Flow

The dimmer flow is similar to the bulb flow but even more straight forward. You can download it here: dimmer-flow.json

It starts out exactly the same where the first node is looking for events coming from any entity starting with light.dimmer. The next node is a simple switch checking if it is a sync dimmer. The Stop node is the same as the one from the bulb flow, which is checking to make sure the dimmer isn't being manually interacted with.

Finally we check if its an on or an off command with the on/off switch node. If its off then we simply turn the bulb off, but if its on we make one check to make sure the bulb is actually off before turning it on. This was done to handle the edge case of using a bulb standalone as well as in a hue light group. Turning the bulb on individually in hand turns on the group as well. When the group turned on it triggered an update of the dimmer from the bulb, and if you don’t check against the light group being on already it would turn on the whole group. (thats confusing, and I’m not sure a better way to explain…)

Manual Dimming

This is where things started to get a bit more tricky. Now I wanted to actually start handing the manual interaction with the dimmers, meaning if I hold down the dimmer paddle I now want the bulbs to start dimming and then stop when I let off the paddle. That sounds pretty straight forward, but it ends up becoming a bit of a headless interaction because we will be getting zero feedback about state until the paddle is released, so the speed and way it behaves is all based on my best guess and referencing what I used to have when I did a similar thing using Indigo. I used the timing from this Indigo Hue Plugin. You can download the flow here: manual-dim-flow.json

For the manual interactions we will be responding directly to the MQTT messages that are coming over the manual_state channel, and the first node will simply be looking for the STOP payload and if it's received it will kill the 400ms timer.

If the payload is not STOP then it's a matter of looking up the bulb that listens to this dimmer, by using the dimmer address and looking up the bulb that has that address set as its sync_address. Once the light is found I decided to create a JSON object of "instructions" that will be iterated over by the timer. The below javascript is what is found in the Dim/Brighten function node.

let light = msg.payload;
let step = 30, max = 20, transition = .4;
let curBrightness = 0, nextBrightness = 0;

msg.instructions = { "increase": true, "transition": transition, "step": step, "count": 0, "max": max, "brightness": 0};

//brightness attribute may not exist if brightening from off state
if(light.attributes.hasOwnProperty('brightness')) {
    curBrightness = light.attributes.brightness;
}

if(msg.manual_state == "DOWN") {
    nextBrightness = curBrightness - step;
    nextBrightness = nextBrightness < 0 ? 0 : nextBrightness;
    msg.instructions.increase = false;
} else {
    nextBrightness = curBrightness + step;
    nextBrightness = nextBrightness > 255 ? 255 : nextBrightness;
}

msg.instructions.brightness = nextBrightness
msg.light = light;

return msg;

It creates an instructions object containing properties saying if its increasing or decreasing brightness depending on if manual_state is set to UP or DOWN, how fast the transition is, the step of how much to change the brightness, and the brightness to be set. Next immediately start updating the brightness of the bulb so there isn't a feeling of delay.

From here the stoptimer node will get kicked off and it will fire every 400ms. The Update Instructions function node will then use and update that instructions object to increase or decrease brightness appropriately and also killing the timer if the button is held down longer than it takes to completely turn on or off the bulb.

let inst = msg.instructions;

inst.count++;

if(inst.count >= inst.max || inst.brightness > 255 || inst.brightness < 0) {
    msg.payload = "stop"
    return [null, msg]
}

if(inst.increase) {
    inst.brightness += inst.step;
} else {
    inst.brightness -= inst.step;
}

return [msg, null];

Manual Fast On

There is one final interaction that I wanted to handle which is the simple fact that if the light was on and the dimmer was on, and I tapped the dimmer again to increase its brightness all the way to 100% nothing would happen.

This would come through as a payload mode of normal and a state of ON. You could also add things to this such as support for "fast" which would be a double tap of the switch for an instant on or off message. I decided to handle fast in the same way I handled normal. You can download the flow here: manual-on-off-flow.json

First uses a get entities node to find the dimmer entity being pressed using its address. Once we’ve got the dimmer, it’s time to figure out if the dimmer was manually pressed and was already on. This is done in the Manual Tap node.

let payload = msg.payload;

msg.dimmer = msg.dimmers[0];
delete msg.dimmers;

let device_on = payload.reason == "device" && payload.state == "ON";
let device_off = payload.reason == "device" && payload.state == "OFF";
let fast = payload.mode == "fast";

let fast_on = msg.dimmer.state == "off" && device_on && fast;
let fast_off = msg.dimmer.state == "on" && device_off && fast;

let fast_on_from_on = msg.dimmer.state == "on" && device_on && fast;
let fast_off_from_off = msg.dimmer.state == "off" && device_off && fast

let on_from_on = msg.dimmer.state == "on" && device_on

if(fast_on || on_from_on) {
    msg.brightness = payload.brightness;
    return msg;
}

There’s more script there than necessary to solve what I actually needed, but I figured I’d try and capture a few of the various states incase I ever wanted to respond to them differently in the future.

Closing Thoughts

Overall I’m pretty happy with my setup. It’s certainly not perfect but 99% of the time it works exactly as you’d expect. One major consideration to be made is you really need to commit to the idea that if the mqtt broker, insteon-mqtt, or home assistant isnt reachable the switches will do nothing. I’ve spent some time figuring out the best way to mitigate this, and my current solution is nothing runs on wifi, and everything is connected to a UPS. Obviously if the power goes out so do the lights, but the UPS is in place to prevent something from not rebooting properly during a short power outage as well as piece of mind that something wont get corrupt by shutting down improperly.

Another is how I’m handling manual dimmer changes. In the current setup the MQTT node is listening to insteon/+/manual_state which is any dimmer in my house. If someone were to manually dim one at the same time as someone else, whoever stops first will stop both lights. After writing this I'm not 100% sure, but there may even be an issue using two switches at the exact same time. I've never tested but assume bad things happen. At the end of the day its only myself and my wife living in this house and the likelihood of this happening is slim.

Originally published at https://jordanrounds.com on August 17, 2020.

I’ve been trying to figure out a good reliable way to have semi complex automations setup for Home Assistant that I can easily edit and debug. Node Red ended up being the solution I settled on.

My goal was to be able to control Hue lights with Insteon dimmers where the dimmers aren’t actually connected to the load and communicating via MQTT. This is the second post in a series about that journey. You can find the first post here:

Setup Insteon-MQTT and integrate with Home Assistant

We will walkthrough installing Node Red in Docker and then setting it up to connect to Home Assistant. Finally we will verify that messages are coming through properly.

Installing Node Red

Being new to Node Red, I had zero idea what I was doing, but knew that I wanted to run it in Docker. I started by looking around at the various Dockerfiles out there and tried to pick the various flows that it seemed like I might need installed. The most important one here being node-red-contrib-home-assistant-websocket. I think the only other one I needed was node-red-contrib-stoptimer. Here’s the Dockerfile I ended up going with:

FROM nodered/node-red

RUN npm install node-red-contrib-actionflows \
    node-red-contrib-home-assistant-websocket \
    node-red-contrib-stoptimer \
    node-red-contrib-time-range-switch \
    node-red-contrib-timecheck \
    node-red-node-timeswitch

From there it was just a simple docker-compose file to get up and running.

version: '3.7'
services:
  node-red:
    build: .
    container_name: "node-red"
    environment:
      TZ: ${TZ}
    image: "nodered/node-red"
    restart: unless-stopped
    ports:
      - "1880:1880"
    volumes:
      - "data:/data"
volumes:
  data:
    name: node-red_data
    driver: local-persist
    driver_opts:
      mountpoint: ${LOCAL_PERSIST}/node-red/data

Run docker-compose up -d and then navigate to the host's ip on port 1880.

Connecting Node Red to Home Assistant

The first thing we need to do to connect Node Red to Home Assistant is generate an access token. I decided to at the same time create a new user in Home Assistant specifically for Node Red. I don’t have any real justification for this step other than I liked the separation. So you could totally skip this bit.

Click Configuration on the left navigation, and scroll down and click Users.

Click the add button in the lower right, and create a new admin user for node red.

After your new user is created click on your current user in the lower left, and click logout. Next login as your node red user. Once logged in again click on the user in the lower left, and scroll down the profile page to the bottom section named Long-Lived Access Tokens and click Create Token.

You’ll then give your token a name and click Ok.

Next you’ll see a modal displaying your access token. Be sure to copy and save it somewhere so we can enter it back in Node Red.

Now its time to go back over to Node Red, and the first thing we will do is drop a server-state-changed node, which is labeled “events: state” from the left hand nodes panel under the Home Assistant section.

Next double click on the node you added, and you’ll see the configuration for that node. Next to the Server field click the pencil icon to add a new server. Then give your server a name, enter its url, and put that access token we created in there. Finally click the add button.

Now you’ll see the configuration for the node. We are just going to test that everything is working next so you can give it a name, pick an entity (one you can change state easily on), and then uncheck only on state change.

From here click done and you’ll see the Flow canvas again with our new node. Next to see if everything’s working scroll up to the top of the nodes list on the left and find the debug node. Drop one of those on the canvas. Once its there click and drag from the gray box on the event node to the debug node.

Finally we can click the Deploy button in the upper right. Click the debug button under it and change the state of the entity through Home Assistant or however you want to change it. Then sit back and watch the messages come through.

Now we’ve got Node Red Setup and working with Home Assistant, and used a debug node to confirm that.

Create a Simple Automation to Control a Light

This is probably the most basic thing we could do. We will use the dimmer and its payload to then trigger a light to either turn on or off. First lets drop an “events: state” node into the flow, and configure it to be an entity that is the dimmer.

Next add a “call service” node to the flow. Double click it to configure it. W will give it a name of “Light”, set the domain to light, set the service to be turn_{{payload}} , and set the entity id to the light entity you want to control in Home Assistant. The key piece to call out here is the service entry, which is essentially taking the payload from the msg object, which will either be on or off, therefore calling the appropriate service of turn_on or turn_off}.

Finally, make sure to connect the two nodes and then go toggle your dimmer and watch the light turn on and off.

What’s Now?

From here we can use Node Red for any types of automations that can be imagined. Searching around the internet there are many great examples others have created, and many times provide the flow to be copied and pasted right into Node Red.

We’ve created this simple automation be the starting point of the automations that will be needed to control Hue lights with Insteon Dimmers coming up next.

Originally published at https://jordanrounds.com on July 1, 2020.

Recently I moved into a new house. My previous house was mostly Insteon devices and I used Indigo running on a Mac Mini as my home automation software. Before moving I had slowly started dabbling with Home Assistant and got a bunch of my Insteon devices communicating with HA via MQTT. This was great as a starting point but now I had two separate automation platforms to deal with and I was slowly moving everything that I could out of Indigo and into HA.

The move was extremely motivating to completely stop using Indigo because I had to start over anyway. Now the question was what should I use to integrate Insteon with HA. There were a few various options I found, including the built in support in HA, but I settled on Insteon-MQTT. I felt like it gave me the flexibility and control that I was looking for.

The main Insteon devices that I use are dimmers and keypads. I ended up settling on them long ago because I couldn’t find anything that even closely compared to the quality of hardware and I especially like the LED display of the brightness on the dimmers. To kick things off I needed to get a testing device setup.

Testing Setup

I built this box with a metal electrical box and power cord from Home Depot and installed a keypad and a dimmer. This gave me the flexibility to not completely have to change switches and not have lights work while getting everything setup. All I did different from a normal in-wall install was connected black to black, white to white, ground to ground, and then capped the load with a wire nut. Just be careful to not electrocute yourself and make sure its unplugged before you put a switch in or take one out.

Insteon-MQTT Install

To start with Insteon-MQTT is extremely well documented. They even provide instructions for setting it up as an add-on in Home Assistant, but I opted for installing it as a Docker container I could manage myself.

version: '3.7'
services:
  inseon-mqtt:
    container_name: 'insteon-mqtt'
    environment:
      TZ: ${TZ}
    image: larizzo/insteon-mqtt
    restart: unless-stopped
    devices:
      - /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A403KDY0-if00-port0:/dev/ttyUSB0
    volumes:
      - config:/config:rw
      - data:/data:rw
volumes:
  config:
    name: insteon-mqtt_config
    driver: local-persist
    driver_opts:
      mountpoint: ${LOCAL_PERSIST}/insteon-mqtt/config
  data:
    name: insteon-mqtt_data
    driver: local-persist
    driver_opts:
      mountpoint: ${LOCAL_PERSIST}/insteon-mqtt/data

Here’s the docker-compose.yaml file I use. All you’ll need to do is make sure the paths to your volumes are correct, and the devices definition which is pointing to the Insteon PLM thats connected to the computer running Docker. Once you have everything configured you’ll just need to run docker-compose.

docker-compose up -d

At this point the container will be up and running but you wont have any devices or the PLM configured. Inside of the config directory that you had mapped as a volume you will find a file called insteon_mqtt.yaml

Config Setup

If you open the insteon_mqtt.yaml file you’ll see that its wonderfully populated and commented out showing examples for configuring each type of device as well as examples for integrating into Home Assistant.

PLM

The first thing we need to do is setup the Insteon PLM. Below is an example of my config for the PLM.

insteon:
  # Serial device:
  # USB PLM modem
  port: '/dev/ttyUSB0'
  baudrate: 19200

  # PLM modem Insteon hex address
  address: 3C.4D.74

  # Device database file storage location.
  storage: 'data'

  # Automatically refresh device states and databases (if needed) at
  # startup.  This may be slow depending on the number of devices.
  startup_refresh: False

The only things you’ll probably need to modify to get the PLM working is the port, which points to /dev/ttyUSB0 and is also what we defined in the devices section of the docker-compose file. Next you’ll need to enter in whatever the actual address is of your PLM which you should find on the back of it.

Devices

Now that we have the PLM setup its time to add our devices. For now I’m just adding a single dimmer but you could just add the addresses of all your Insteon devices in here right now. Insteon dimmers normally have an address sticker on the front of them.

devices:
    # Dimming devices (outlets, wall switches, lamp modules, etc).
    dimmer:
      - 41.ad.4f: 'dimmer'

You’ll be putting the address first followed by a colon and then a string for the name of the device.

If for some reason you don’t know the address of the device you are able to get it by looking at the logs of insteon-mqtt as long as the device is powered and sending a command. If you are in this situation, restart the docker container after configuring the PLM and go checkout the logs to get your addresses. When I went through this process I used a label maker to add new address stickers to all of my dimmers.

MQTT

Next we need to configure MQTT. You’ll need at a minimum the address to your broker and the port. Optionally if you have authentication turned on the username and password.

mqtt:
  broker: 192.168.1.123
  port: 1883
  
  # Optional broker login data.
  username: yourusername
  password: yourpassword

Once the broker is setup you can take a look at the topics for Dimmers and any of the other supported types of Insteon devices you might need. Below is an example of what my dimmer topics look like.

dimmer:
    state_topic: 'insteon/{{address}}/state'
    state_payload: >
       { "state" : "{{on_str.upper()}}", "brightness" : {{level_255}}, "reason" : "{{reason}}", "mode" : "{{mode}}", "address" : "{{address}}" }

    manual_state_topic: 'insteon/{{address}}/manual_state'
    manual_state_payload: '{ "manual_state" : "{{manual_str.upper()}}", "address" : "{{address}}" }'

    on_off_topic: 'insteon/{{address}}/set'
    on_off_payload: '{ "cmd" : "{{value.lower()}}" }'

    level_payload: >
       { "cmd" : "{{json.state.lower()}}",
         "level" : {% if json.brightness is defined %}
                      {{json.brightness}}
                   {% else %}
                      255
                   {% endif %} }
                   
    scene_topic: 'insteon/{{address}}/scene'
    scene_payload: '{ "cmd" : "{{value.lower()}}" }'

It’s very close to the defaults except I’ve included reason, mode, and address in the state payload as well as uncommented the manual_state topic and payload, which will send dimming start and stop payloads.

Restart, Join, Pair, and Refresh!

At this point all the configuration we need for insteon-mqtt is complete. Before we do anything else go ahead and restart the container.

docker-compose restart

Once the container is back up we need to go through the process of joining, pairing, and refreshing all the devices. This process can be done from the command line or using MQTT. I chose to do it via the command line using docker exec, and I wrote a simple bash script to help keep it simple.

While it isn’t necessary I did also choose to factory reset all my dimmers before adding any of them. This can be done by pulling out the small button below the dimmer button, wait ten seconds, and then press in and hold it until the switch stops beeping and then a couple seconds later you’ll hear a double beep confirming that the reset was successful. You can find the instructions in the manual as well.

Using MQTT

The topic would be:

insteon/command/aa.bb.cc

The payload would be one of these three:

{ "cmd" : "join"}
{ "cmd" : "pair"}
{ "cmd" : "refresh"}

Using Docker Exec

You can join and pair each device using the appropriate commands, and when done call the refresh-all command. Alternatively you could call refresh on each one individually.

docker exec -d your_instance_name insteon-mqtt /config/insteon_mqtt.yaml join aa.bb.cc

docker exec -d your_instance_name insteon-mqtt /config/insteon_mqtt.yaml pair aa.bb.cc

docker exec -d your_instance_name insteon-mqtt /config/insteon_mqtt.yaml refresh-all

Bash Script

Lets call this script insteon-mqtt.sh. Make sure that the file’s permissions are executable, and then type ./insteon-mqtt.sh on the command line.

#!/bin/bash
INSTANCE_NAME='insteon-mqtt'
CONFIG_FILE='/config/insteon_mqtt.yaml'
LINE='-------------------------------------'

echo 'Insteon MQTT Management'
echo
echo 'What would you like to do?'
echo $LINE
echo '1) Join Device'
echo '2) Pair Device'
echo '3) Refresh All Devices'
echo '4) Refresh Device'
echo $LINE

read -p 'Choose option: '
echo

if [ ${REPLY} -eq 1 ]; then
  echo "Joining Device"
  echo $LINE
  read -p 'Device Address (aa.bb.cc): ' address
  echo
  echo "Joining Device: $address"
  docker exec -d $INSTANCE_NAME insteon-mqtt $CONFIG_FILE join $address
  #docker exec -d $INSTANCE_NAME kill -HUP 1
elif [ ${REPLY} -eq 2 ]; then
  echo "Pairing Device"
  echo $LINE
  read -p 'Device Address (aa.bb.cc): ' address
  docker exec -d $INSTANCE_NAME insteon-mqtt $CONFIG_FILE pair $address
  #docker exec -d $INSTANCE_NAME kill -HUP 1
elif [ ${REPLY} -eq 3 ]; then
  echo "Refresh All Devices"
  echo $LINE
  docker exec -d $INSTANCE_NAME insteon-mqtt $CONFIG_FILE refresh-all
elif [ ${REPLY} -eq 4 ]; then
  echo "Refresh Device"
  echo $LINE
  read -p 'Device Address (aa.bb.cc): ' address
  echo
  echo "Refreshing Device: $address"
  docker exec -d $INSTANCE_NAME insteon-mqtt $CONFIG_FILE refresh $address
else
  echo "Please enter a valid option."
fi
exit 1

Testing MQTT

Now that everything should be added, paired and ready to go its probably worth testing it out before trying to put everything in Home Assistant. Home assistant has some built in MQTT debugging under the Developer Tools.

I prefer to use MQTTBox which is a free download. It allows for subscribing or publishing to multiple topics easily, and keeps your setup saved for later.

Once you are subscribed to your topic using the correct address of your device you should start to see messages coming through when you turn it on or off. If you aren’t seeing messages coming through, be sure to double check the address of your device is correctly entered in the insteon_mqtt.yaml file, and in the topic you are subscribed to.

Additionally its always worth checking in on the logs from insteon-mqtt. They are extremely verbose and helpful.

docker-compose logs

Adding to Home Assistant

Finally we need to add these devices into Home Assistant using MQTT Templates. Luckily there are very clear examples inside the insteon_mqtt.yaml file. Under the MQTT sections of each device type you will find examples and instructions for adding them to Home Assistant. We will be using the Dimmer as our example.

light:
  - platform: mqtt
    schema: json
    name: "insteon 1"
    state_topic: "insteon/aa.bb.cc/state"
    command_topic: "insteon/aa.bb.cc/level"
    brightness: true

So what now?

At this point we’ve successfully gotten an Insteon dimmer to communicate over MQTT and be integrated into Home Assistant. You can now automate and interact with that switch like any other dimmer that would have been added over Z-Wave or some other protocol.

I didn’t end up stoping at this point though. In my old setup with Indigo, my Insteon dimmers controlled my Hue bulbs, and the Hue bulbs would update the state of the LED on the dimmers to reflect their brightness.

Soon I’ll walk through what that process looked like and explain the different approaches I took until finally settling on Node Red being how I managed the automation.

Originally published at https://jordanrounds.com on June 25, 2020.

If you start looking around the internet there are tons of different articles about getting this setup. They all vary in complexity and at times get a bit confusing. I’ve gone down this path before without Docker setting up an Ubuntu instance on Digital Ocean and installing everything from scratch. It was a complete nightmare, but after many many hours or days I was able to get it working. Once I started to understand Docker and had everything running locally at home it seemed like it would be a much easier to maintain there.

I ditched my Digital Ocean droplet and started researching how to do this in Docker on my home server. There was one requirement, which was I need a container that supported the DNSimple DNS plugin since I host my sites through DNSimple. It turns out there is an absolutely beautiful container linuxserver/letsencrypt that does everything I needed. It supports all the various plugins for certbot.

Prerequisites

The first thing I did was add an A record with the actual domain (example-domain.com), and a wildcard subdomain (*.example-domain.com) to DNS and pointed it at my home ip. I then forwarded ports 80 and 443 to my home server.

docker-compose.yaml

Below is the Docker Compose file I setup. Its pretty much copy and paste from their example. The main things to point out are: SUBDOMAINS=wildcard, VALIDATION=dns, and DNSPLUGIN=dnsimple.

Once that’s saved, you just need to run docker-compose up -d

DNSimple Configuration

After the container is running you’ll need to go modify the configuration for the DNSimple plugin and put your token in there. To get this token you’ll need to go to your DNSimple Account page and click the Automation tab on the left. Then under API Tokens you’ll click the new button, give it a name, and copy the token.

Now that you have the token your going to navigate to config/dns-conf/dnsimple.ini which is wherever you pointed your volume to and paste that token in replacing the default one thats in there. Once you’ve saved that file you can then restart the container with docker-compose restart At this point you should now be able to navigate to your url and will be presented with the default page.

NGINX Subdomain Config

Next thing I did was configure a subdomain to point to my Home Assistant install. I used the default example that they provide in the documentation for the container and also this post with a few minor changes/additions.

I’ll call out the key changes that I made. For server_name you can enter your subdomain.*. Next you’ll need to add proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection “upgrade”;. Then finally you’ll need to change your.ip.here to be the internal IP of the machine hosting Home Assistant. Once this is all setup the final thing left to do is run docker-compose restart and you should be up and running.

But my IP is dynamic and changes

Your home IP is most likely dynamic and could change at anytime. Obviously this will cause issues, and everything we’ve setup will break since that A record will no longer point to the correct place. DNSimple provides an easy solution to this problem. They provide a shell script for updating DNS with your current IP using the same token approach that the dns plugin for DNSimple that Certbot uses.

For TOKEN it’s the same process as before. I’m pretty sure you can use the same one generated previously, but I chose to generate a new one. The ACCOUNT_ID I grabbed from the URL when logged into DNSimple. ZONE_ID is obviously the domain being updated. The RECORD_ID I found by clicking on edit for a DNS record, and then pulling the ID from the URL.

Automate the Script

Once I got that script sorted out, I needed a way to get it to run regularly to make sure the IP was up to date. I opted for creating a Docker container with this being its sole responsibility. Obviously this could just be a cron job you ran on the machine, but what fun would that be?

I created the Dockerfile from alpine:3.11. I installed curl so that the script could execute the command. Under /etc/periodic/15min you can drop any scripts you want run and cron will kick them off. I copied the script in there, and then finally need the container to run the command crond -l 2 -f. Thats really all there is to it, so all that was left was to run docker-compose build and then docker-compose up -d and its up and running.

Previously I wrote about setting up Home Assistant running in Docker along with Portainer to provide a GUI for management. Since then I’ve spent a fair amount of time coming up with a setup that is something I’m comfortable with and feel is able to be easily maintained. I’m assuming that I’ve gone through a lot of steps that are similar to what others have.

I got up and running with simple docker run commands that were cobbled together from random posts and examples across the internet. I would run the container with its various command line options and tweaking until it worked. Once I got something solid I would copy that into some of my notes so I had it for later. This whole process felt disorganized and likely to end up in a sad failure when I tried to come back to any of it months later when I would have inevitably forgotten how and why I had done anything.

I then realized that there was docker-compose which initially was quite confusing. Reading the documentation made it seem like it was meant for managing multiple container docker applications, but I only needed one container and initially thought this was an issue. Turns out just because it can support multiple doesn’t mean you cant just run one container. Docker Compose files provided a so much nicer and organized approach to setting up the configuration and running a container.

Where I stored all of my Docker stuff

In /home/docker is what I settled on. Within that directory I created a new directory for each of my containers, and their associated mounts, configs, etc. This ended up looking similar to:

/home
   |__ /docker
         |__ /mosquitto
               |__ /config
               |__ /log
               |__ /data
         |__ /portainer
         |__ /samba   

This seemed easy to wrap my head around, find my data, and navigate.

docker run vs. docker-compose up

Heres and example of the docker run command to bring up my mosquitto container.

sudo docker run -it --name mosquitto -p 1883:1883 -p 9001:9001 -v /home/docker/mosquitto:/mosquitto/config -v /home/docker/mosquitto/data:/mosquitto/data -v /home/docker/mosquitto/log:/mosquitto/log eclipse-mosquitto

Now compare that to what it looks like in a docker compose file.

Both of these are doing the same thing, but obviously the Docker Compose file is far easier to read.

Understanding Volumes

So now that I’ve settled on using Docker Compose and it appealing to my need for organization the next step was figuring out what all those -v or volume options actually meant. Since it was just copy paste to start I had no idea what was going on. Realistically it was creating those directories local to where I ran docker compose and persisting the data on the host’s file system. This seemed great at first but requires that that directory structure had to be the same if you were to move the containers to a different host, which is less than ideal.

It turns out if you don’t declare them Docker takes care of it for you and just creates its own. This led to me to start understanding what volumes were in Docker, which you can find in:

/var/lib/docker/volumes

Docker will just give them random names and create them. You also have the option of specifying a volume and giving it your own name, which can also be done in the Docker Compose file.

volumes:
   data_vol:
      name: my-named-volume

Doing this will give you named volumes managed by Docker. This seemed like a solid solution, except that everything is then located in /var/lib/docker/volumes It was pretty annoying bouncing over to that directory to change config files, and then back to /home/docker/. This felt like the “right” thing to do, and the proper Docker pattern to follow, but I didn’t like it.

Introducing local-persist

I was talking with a friend and he told me he had found this Docker volume plugin called local-persist. This changed things up quite a bit. I was now able to persist data in a local directory but still have named volumes. The real kicker was that I felt like I still doing things the “right” way. I now had the ability to persist data locally and maintain named volumes. If I removed the volume my data lived on. If I wanted to point those volumes at an external source like my NAS, I now had that option. That original Mosquitto Docker Compose file now turned into this:

That $LOCAL_PERSIST environmental variable is set in /etc/environment to LOCAL_PERSIST=”/home/docker/.local-persist”. This made it easy for me to use it across multiple Docker Compose files.

In Conclusion

I now feel like I have a pattern of setting up Docker containers using Docker Compose using the local-persist plugin that makes me feel like I’m in control and have something I can easily maintain and move around if I chose to. Everything I have talked about here was learned over the course of a couple weeks and is just my opinion. It’d be great to hear from others what their approach is.

I’ve been running Home Assistant on a Raspberry Pi 4 for around 7 months or so, and have been very happy with it. That being said there were things that were a bit frustrating, such as slow reboot times, and the constant fear of killing the micro sd card. A friend of mine moved his setup over to a NUC (mini pc or whatever it’s called) and had nothing but great things to say, so I decided to make the move.

I’m going to walk through the steps I took to build and setup the NUC, enable SSH, install Docker and Portainer, and finally get Home Assistant running. I opted for Home Assistant “Supervised” (formerly Hassio), not Home Assistant Core, so that I would continue to have the ease of updates, and add ons that I’ve become accustomed to.

Putting together the NUC

I went around in circles trying to figure out what hardware to buy. Do I want an i3, i5, or i7? Should I get an 10th, 8th, or older generation? Should I just go with the same machine my friend used? At the end of the day I decided to get some current powerful hardware that would allow for me to easily run Home Assistant and any other number of services I might want, as well as just have a more future proof machine to mess with. Heres the hardware I ended up choosing:

• Intel Nuc 10 (NUC10i7FNH1)
• Kingston HyperX Impact 16GB Memory
• Samsung 970 EVO Plus SSD 500GB — M.2 NVMe

First we need to flip the NUC over and remove the 4 screws that hold the cover on, and gently pull the cover off.

Next we can install the ssd drive. To do this we will remove the screw back by the usb ports on the rear. Once the screw is out you can slide the ssd drive in and tighten the screw back down.

Finally we need to install the Memory. Just slide each module in with the top angled up and then gently push down until it snaps in.

At this point all thats left to do is screw the cover back on, and plug in the power, monitor, and keyboard.

Updating the BIOS

Since we are starting fresh I figured it wouldn’t hurt to update the bios to the latest version. Obviously this can fail and the whole thing could be bricked, but I was feeling lucky enough. (this step could be skipped)

To start with go to the intel download center. Change the operating system to OS Independent and look for the bios for your model of NUC. In this case mine was BIOS Update [FNCML357].

You’ll want to download the FN0039.cap file. The method we’ll be using to do the update is the power button method. The instructions can be found here, but it’s a pretty straight forward procedure.

Start off by grabbing a USB drive and it’ll need to be formatted. I used Disk Utility on MacOS and formatted it to MS-DOS (FAT). Once thats done put the .cap file you downloaded on the USB drive.

With the NUC powered off completely insert the USB Drive. Next, you will hold down the power button for 3 seconds after which it will turn red and you can release it.

The NUC will then boot and you’ll be presented with a screen of different options. You’ll want to pick “Update Bios” and therefore can press F7 on the keyboard. Next you’ll be presented with a screen to choose the flash drive, then the .cap file. You’ll see instructions for navigating the screens at the bottom.

Eventually you’ll make it through the screens where it’ll ask you to confirm the BIOS update, the NUC will reboot, and you will then see the Flash Update screen showing you the progress of the update.

Installing Ubuntu 18.04.4

Next we will be downloading ubuntu, imaging a usb drive, and installing the operating system. I opted for the desktop minimal version just to give myself something to mess around with. We will be downloading two things: Ubuntu and Balena Etcher. Once they are both downloaded get Etcher installed and opened up. First you’ll select the image for Ubuntu, next you’ll select the USB drive, and then click flash.

After Ether is finished you can remove the USB drive from the computer and insert it into the NUC with the power off. Now we will do the same thing we did when updating the BIOS and hold down the power button for 3 seconds and then release it. Next you’ll see the same screen from updating the BIOS but this time you will be pressing F10 which will take you to the boot menu. Choose your USB drive, then at the next screen select “Install Ubuntu.”

Now all you’ll have to do is walk through Ubuntu’s installer screens and then we are good to go!

Enable SSH

I suppose getting SSH working isn’t completely essential but it sure is handy to be able to sit at a laptop and just ssh into the NUC. Also, it’s also pretty straight forward, so why not?

sudo apt update

sudo apt install openssh-server
(press y)

sudo systemctl enable ssh

sudo ufw allow ssh

sudo ufw enable

This should have enabled ssh, and allowed traffic over port 22 through the firewall.

Install Docker

I chose to install Docker using the repository as it’s the recommended method.

sudo apt-get update

sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common

Install Docker’s official GPG key and verify the fingerprint (0EBFCD88)

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

sudo apt-key fingerprint 0EBFCD88

Setup the stable repository.

sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

Install Docker Engine

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

Install Portainer

Installing Portainer is not necessary but is extremely useful as it gives you an actual GUI to interact with Docker. If you are new to Docker like me this will be extremely helpful. First you will create a volume for the portainer data and then create the container.

docker volume create portainer_data

docker run -d -p 9000:9000 -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer

Once this is complete you can navigate in your browser to the NUC’s IP address port 9000. (ie: 192.168.7.4:9000) From there you will be prompted to create the admin account, then choose the Docker environment you want to manage, which is “Local.” After connecting to local you will be logged in and presented with a screen similar to this:

From here you will be able to navigate around to view your containers, volumes, etc.

Installing Home Assistant — Finally!

So looking around the internet there didn’t seem to be a ton of tutorials installing what was called Hassio in Docker. I found one here and here. They are both pretty similar but out of date, since the URL to the repo has changed. The new repo for Home Assistant Supervised lives here. It took me a while to figure out what changed, what the correct URL was, etc. Because of the name changes I even glazed over the official documentation not realizing it was exactly what I needed. Run the commands listed below and Home Assistant will be installed and running in its various Docker containers.

sudo su

add-apt-repository universe

apt-get install bash jq curl avahi-daemon dbus software-properties-common apparmor-utils apt-transport-https ca-certificates network-manager socat

systemctl disable ModemManager 

systemctl stop ModemManager

curl -sL https://raw.githubusercontent.com/home-assistant/supervised-installer/master/installer.sh | bash -s -- -m intel-nuc -d /home/docker/hassio

There are two things to call out:

• -m is the machine type (in our case intel-nuc)
• -d is me saying I want the default data storage location

There are a few other options for the installer that are explained on the Github page.

You will then need to navigate to (your-nuc-ip:8123) and you’ll be prompted to setup your user for Home Assitant.

In Conclusion

The whole setup process is definitely a bit more complex than installing Home Assistant on a Raspberry Pi, but now that I’m setup on the NUC everything is so much more snappy and I feel like I’m more in control and have options I didn’t know existed. That control definitely comes with quite the learning curve, but if you’re patient and willing to do some reading its totally worth it!

Sonoff Basic R2 + Tasmota

Switch Template:

The template is pretty straight forward, and you can reference the docs for adding an MQTT Switch and all the different configuration options that are available. You can copy the template below into config/configuration.yaml.

This switch template is assuming you used the same topic formatting in my other article. Be sure your topics match what you configured in the Tasmota web ui.

The Automation

This automation will turn on the lights in the morning around when I get up, then shut them off again around work. They then come on at night and shut off around bed time.

If you were using this automation for outdoor lights you might want to use the trigger for sunrise and sunset.

trigger:
  platform: sun
  event: sunrise

Wrapping Up

All thats left to do at this point is to check the config, and if there are no errors then restart Home Assistant. In the left nav click on Configuration and then Server Control. You’ll see this screen.

Once you’re here click the Check Config button and give it a minute. You should see a Configuration valid message. If not you will see errors telling you the lines that have the issue.

After the configuration is validated, click the restart button down at the bottom to restart Home Assistant.

Now you’re set to go with some automated Christmas lights.

This is a walkthrough of flashing a Sonoff Basic R2 device with the Tasmota firmware so that it can connect to an MQTT broker.

I decided to write this because I wanted an easy way to automate my Christmas lights through Home Assistant. Doing this for the first time offered many different paths and the internet is full of a bunch of tutorials. Mainly I wanted to put together a clear end to end of everything needed and how to do it using macOS. All setup and screenshots will be done using macOS Catalina. The one assumption made is that you’ve already got an MQTT broker setup.

Hardware used:

USB Serial Adapter

Jumper Wires or Header Pins

Sonoff Basic R2

Software used:

NodeMCU PyFlasher

FTDI VCP Drivers

tasmota.bin

MQTTBox

Start with the Software

Download Tasmota

You can download the latest version of Tasmota from the releases page on Github. The current version as of writing this is v7.1.2. Scroll down through the list and download the file named tasmota.bin towards the end of the list of files.

Note: There are others you can use most of which are in various different languages. An explanation of the different versions is on the release page if you are interested. Once downloaded set that to the side for now.

Let’s download and install PyFlasher.

Here you will find the releases page on Github. Go ahead and grab the latest release, which currently is V4.0.

Next download the driver for the USB Serial Adapter from FTDI.

Be sure to pick the right one for the operating system you are on. Installing this on macOS is fairly straight forward with one gotcha.

During the installation you are going to have to allow the install through Security & Privacy within System Preferences. Under the general tab there is a section labeled “Allow apps downloaded from.” Here you will see a button to click to allow the new driver install. Without doing this the USB Serial Adapter will never show up.

You should see a notification like this:

Moving on to prepping the Sonoff R2

Rip everything apart!

First step is to take the caps off the left and the right side of the R2. Then you are going to push the back plastic through the openings on the left and right to detach the top from the bottom.

Once thats all done you will just be needing the board and can set everything else off to the side.

Next let’s get the USB to serial adapter ready.

Make sure the little black jumper is connecting the 3v3 pin to the JP pin.

Go ahead and connect your four jumper wires to the remaining pins, which are RXD, TXD, GND, and VCC.

Note: If you don’t have jumper wires and want to use the cable that came with the serial adapter, you could alternatively insert some header pins into the female end of that cable and have the same setup as below.

Through the back of the board insert the jumper wire pins into the appropriate holes. They are as follows from the serial adapter to the R2 board.

• GNG → GND
• VCC → 3V3
• TXD → RX
• RXD → TX

If you have the serial adapter plugged in you should see the R2 start to light up and flash green. Now turn the board over and let it rest on the jumper wires.

Flashing time!

Get the R2 into programming mode.

Everything is now set to begin flashing the board.

1. Unplug the serial adapter.
2. Hold down the tall black button.
3. Plug in the serial adapter.
4. Release the button.

The ESP8266 chip on the R2 board will now be in programming mode.

Flashing Settings

Open up NodeMCU PyFlasher.

First click the select box for Serial port and look to see that your serial adapter shows up.

Note: If it doesn’t show up try pressing the refresh button to the right. If it still doesn’t show up, try restarting your computer to fix the issue.

Click the browse button and select the location where you downloaded tasmota.bin. Next select the following settings.

• Baud rate: 115200
• Flash mode: Dual Output
• Erase flash: yes

After you have everything set, click the Flash NodeMCU button and wait until it tells you to restart the R2.

At this point unplug the serial adapter and plug it back in to get the R2 to reboot.

Time to Configure Tasmota

Setup Wifi

Open the wifi settings on your phone. Look for a network being broadcast thats named tasmota-xxxx where xxxx will be some numbers. Tap on that network and you should be prompted with a wifi configuration screen.

Next you can tap the Scan for wifi networks link and then select your network from the list that shows up or directly enter the ssid into the AP1 SSId field. Then enter your password in the AP1 Password field.

Once you have everything entered tap on the Save button and you will see a screen telling you the R2 is restarting and connecting to your network.

Get the IP Address

After the Sonoff R2 restarts and connects to your network you’ll need to get its ip address.

Note: This can be done through your router or an ip scanner application. It will show up with a hostname of tasmota-xxxx just as it did when we connected to it through wifi in the previous step.

The photo here is an example of what I saw when looking for the newly connected wifi device inside of my Eero App.

Open Tasmota

In your browser put in the ip address and you will see the main page for your R2.

Next click on Configuration and then Configure MQTT and you will see a screen like below.

Start by entering in the hostname or ip of your MQTT broker. Optionally a different port, username and password. The topic should be a unique identifier for your R2, so go ahead and change the default of Tasmota to whatever you’d like to name it.

At this point you could simply save and the Sonoff R2 would now be sending and receiving MQTT messages.

Note: I did make the conscious choice to configure my Tasmota flashed devices manually with Home Assistant and not use the auto discovery feature for no other reason that I wanted complete control and the auto discovery scares me. I also added Tasmota to the beginning of the full topic and all future devices I add will use Tasmota as the root of their topics as well.

What will the topics look like?

You’ve defined your unique %topic% and the %prefix% will be one of 3 things: cmd, stat, and tele. Cmd is for issuing commands or asking for status. Stat will report back status or configuration messages. Tele will report telemetry info.

In my case an example topic would be:

tasmota/stat/sonoff_basic

The payload might look like:

{“POWER”:”ON”}

Note: I used MQTTBox to do my testing.

Optional Configuration

I also went into Configuration → Configure Other and changed the Friendly Name to be the same as the Topic name that I configured in MQTT.

The final thing I did was set the PowerRetain option in the console.

From the main menu click on Console. In the input type “PowerRetain ON” and press return. The state of the power messages will now be retained and anytime something such as Home Assistant connects to the broker they will know the last state of the device.

Putting it Back Together

So, I chose to add the R2 to an extension cord, but you could easily do the same thing to add it directly to the cord of anything you want to plug into an outlet. I used an extension cord since this is going to control my Christmas lights and I’d like to reuse it for other things once Christmas is over.

First go ahead and pop the R2 board back into the plastic enclosure. Set it in the base and snap the top on. The first time I did this I attached the cord before doing this and then realized I had to take the whole thing apart again.

Next let’s get the extension cord ready. You’ll need a wire stripper and a scissors or knife.

Start off by cutting the extension cord. I cut mine near the plug and gave it enough length that the R2 will rest on the ground. You can make the cord whatever length you’d like so if you want a 1 foot cord just cut off the excess.

Once you have it cut, take a scissors or knife and cut between the two wires about a half inch or so. Then take the wire stripper and strip about 1/4" off. It really doesn’t need to be much.

Note: You might be wondering which wire goes in L (load) and which goes in N (neutral). If you look and feel the cord you’ll notice that one side is smooth and one is ribbed or not smooth. The not smooth one will be inserted into N.

Insert the male end or piece of the cord with the actual plug in the end of the R2 that says Input. Then tighten it down with a small flat head screwdriver.

Ribbed Wire → N

Smooth Wire → L

Do the same with the other end of the extension cord on the Output side of the R2. Once both parts of the cord are secured put the caps on either side and tighten down the screws included in the box with a small phillips screwdriver.

Now go plug it in and you are set to go!

Wrapping Up

These are all the steps for setting up the Sonoff R2 using Tasmota and getting it talking with your MQTT broker. At this point you can integrate and control it however you would like either via its web interface or over MQTT. In another article I’ll show how to manually add these devices to Home Assistant, and setup some basic automations.

Adding Sonoff Basic R2 flashed with Tasmota to Home Assistant