Connecting a stepper motor to Hassio/Home Assistant using a NodeMCU via MQTT

The following guide will take you through how to connect a stepper motor to your Home Assistant/Hassio using a NodeMCU via MQTT. What you will need (or equivalent):

Step 1 – Connect your NodeMCU to the driver board and stepper motor

First of all, connect up your NodeMCU to the controller board using the following pin mappings. These are required as the code used below maps to these pins.

Step 2 – Install Arduino software, required libraries and configure

  • Software Install:
  • Board Support:
  • Install Board Support:
    • Install the board to allow additional board support for the NodeMCU. Select Tools –> Board –> Board Manager
    • Once loaded, search for ‘ESP’ and select and install the ‘ESP8266’ board
  • Install Libraries:
    • There are two libraries required for this code, ‘PubSubClient’ and ‘Stepper’
    • Click on Sketch –> Include Library –> Manage Libraries
    • When it has loaded, search for ‘Pubsub’ and select ‘PubSubClient’ and install
    • Then install ‘Stepper’ library by searching for ‘Stepper’ and installing
  • Configure Board:
    • Now you will need to configure the board by selecting board under Tools –> Board and find the ‘NodeMCU 1.0 (ESP-12E Module)’
    • Select the following options:
      • Upload frequency speed of ‘115200’
      • CPU frequency of ’80 MhZ’
      • Flash Size of ‘4M’
    • You shouldn’t need to change the others settings, so leave as default
    • Select the Port once you have plugged the NodeMCU into your computer. In my case it is coming up as ‘COM5’.

Step 3 – Configure Home Assistant MQTT

  • In your Home Assistant configuration.yaml file, make sure you have added in the MQTT component and selected a password
  • You can write the password directly in here or use the secrets file as I’ve done below and leveraged off the existing http_password:
mqtt:
password: !secret http_password

Step 3 – Upload and compile code on NodeMCU

For the code used in this example, I have used the original code from osoyoo.com (http://osoyoo.com/2017/05/17/nodemcu-lesson-16-stepper-motor-mqtt/) and adjusted as required. For a copy of the custom code used, download this file and update the following details:
  • The wifi ‘ssid’ and ‘password’ to your own network
  • The ‘mqtt_server’ to the IP address of your Home Assistant
  • Update the client.subscribe(“chickenDoor”) to the relevant topic. I’ve put ‘chickenDoor’ which is the topic that will be published to via Home Assistant and used in my scripts in the steps below
For noting:
  • ‘userName’ is the default home assistant MQTT username (i.e. ‘homeassistant’) and ‘passWord’ is the one that was selected in the MQTT component in your configuration.yaml file in Step 3
  • ‘clientId’ doesn’t matter for HomeAssistant, so put anything here
  • Changes to the original code:
    • I have added a few additional options such as the clockwise and counterclockwise loop (values 3 and 4), which runs the stepper 72 times. This is the amount I need my stepper to spin for the chicken door to go fully up and down. I’ve also put a delay of 50 so that it gives the motor enough time to think and continues the revolution immediately
    • I’ve also added in another option to turn off the motor (value 0) as the stepper will stay on and stay in place at the end of the cycle unless directed to turn off
    • Some other tweaks to make the Serial monitor show additional details and status

Step 4 – Configure Home Assistant/Hassio Scripts & Automations

  • Now in Home Assistant, I’ve made a few scripts which publish to the ChickDoor topic. These correspond to the values in the code, 1 and 2 for incremental spins and 3 and 4 for longer spins. I’ve also put in the stepper off for a value of 0.
  • I’ve also added a couple of automations to open and close the door. The first one is to close the chicken door at sunset.
  • This uses the sun trigger for when it is sunset and it will call the chicken door close (anticlockwiseloop) script and then turn off the stepper.
Scripts:
stepper_clockwise:
  alias: Chicken Door Step Up
  sequence:
    – service: mqtt.publish
      data:
        topic: “chickenDoor”
        payload: “1”
stepper_anticlockwise:
  alias: Chicken Door Step Down
  sequence:
    – service: mqtt.publish
      data:
        topic: “chickenDoor”
        payload: “2”
stepper_clockwiseloop:
  alias: Chicken Door Full Up
  sequence:
    – service: mqtt.publish
      data:
        topic: “chickenDoor”
        payload: “3”
    – service: script.turn_on
      data:
entity_id: script.stepper_off
stepper_anticlockwiseloop:
  alias: Chicken Door Full Down
  sequence:
    – service: mqtt.publish
      data:
        topic: “chickenDoor”
        payload: “4”
    – service: script.turn_on
      data:
        entity_id: script.stepper_off
stepper_off:
  alias: Chicken Door Off
  sequence:
    – service: mqtt.publish
      data:
        topic: “chickenDoor”
        payload: “0”
Sunrise Automation
The following automation is configured to open the chicken door and execute the clockwise loop script when the sun is rising.
Sunset Automation
The following automation is configured to close the chicken door and execute the anticlockwise loop script when the sun is setting. I’ve added a delay because my chickens like to stay out a bit later.

Step 5 – Compile and Upload

  • Just to make sure everything is fine, compile the code by clicking ‘Sketch’ –> ‘Verify/Compile’
  • Once completed, click ‘Upload’ to load the code into the NodeMCU
  • To view the status of the device, click ‘Tools’ –> ‘Serial Monitor’ (do this while it is uploading so that you don’t miss the log when the device starts)
  • If all is well, the Serial Monitor will show ‘Attempting MQTT connection.. connected’.

Step 6 – Test the scripts

  • Execute the scripts that were configured in ‘Step 4’:
  • When executing scripts, the Serial Monitor should show the commands received and action taken:
If everything went well then you should have a working stepper motor. This is a really cheap way to get a stepper motor working and connected to your Home Assistant/Hassio. There will be other uses besides a chicken door (e.g. blinds). Feel free to post here or on my video for any suggestions, feedback or questions.