Skip to main content

SenseCAP Indicator - Home Assistant Application Development

Introduction​

Get One Now 🖱️

Unlock the full potential of your smart home by integrating the SenseCAP Indicator with Home Assistant. This powerful combination allows you to monitor and control your environment with unprecedented ease.

Learn how to seamlessly integrate your SenseCAP Indicator with Home Assistant using MQTT in this comprehensive guide.

Before we begin, let's explore your options for setting up Home Assistant. Home Assistant can be easily installed on two dedicated hardware options:

note

For sure, you have various options to install HA by following Installation - Home Assistant (home-assistant.io).

The affordable Home Assistant Green is the easiest way you can start using Home Assistant. It's plug-and-play and comes with Home Assistant already installed.

To maximize the capabilities of Home Assistant, we recommend using either Home Assistant OS or Home Assistant Supervised. Both options offer advanced features and greater customization options, allowing you to tailor your smart home experience to your exact needs.

Now, let's get started with the integration process. Follow these three main steps to get your SenseCAP Indicator working with Home Assistant:

  1. Install Home Assistant OS
    1. Install Add-ons
    2. Set Up MQTT Integration
  2. Build And Flash Firmware
  3. Add MQTT Devices
  4. Set up A Dashboard

Prerequisites​

Before we begin, make sure you have read the User Guide of the SenseCAP Indicator Board to familiarize yourself with its software and hardware information.

Install Home Assistant OS​

Home Assistant is a powerful open-source home automation platform that focuses on privacy and local control. It offers a customizable and flexible framework to manage and automate all your home devices from a single, unified platform.

With Home Assistant Yellow You can follow the instructions provided here. Also, to run on any type of Raspberry Pi or a local server, you can follow this instruction step by step.

Once you installed, getting into this page means you can go to next step.


Don't know how to onboard Home Assistant?

Once you installed the Home Assistant, check Onboarding Home Assistant - Home Assistant for details.

Step 1: Install Add-ons​

Add-ons feature required

Home Assistant Yellow comes with Home Assistant Operating System can be easily installed Add-ons. However, Home Assistant Container does not support Add-ons, which means you need to install a MQTT broker application aside from Home Assistant. For details, check the installation Methods.

The next step is to install the Mosquitto Broker and File Editor. Mosquitto is an open-source message broker that implements the MQTT protocol whereas File Editor allows you to modify the configuration.yaml file without accessing the terminal .

In Home Assistant Yellow, you can install the Mosquitto Broker and File Editor using the Add-ons feature.

tip

For convenience, show the 'File editor' in sidebar:

Now we get two add-ons.

Step 2: Set Up MQTT Integration​

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol that's crucial for connecting your SenseCAP Indicator Board to Home Assistant. To enable this functionality, you need to add the MQTT integration to your Home Assistant setup.

Adding the MQTT integration allows Home Assistant to communicate seamlessly with your SenseCAP Indicator Board, enabling real-time data exchange and control. This bi-directional communication is essential for monitoring sensor data and sending commands to your device.

To set up the MQTT integration:

  1. Navigate to the Integrations page(Devices & Services -> Integrations) in your Home Assistant dashboard.
  2. Search for "MQTT" and select it from the list. (If not discovered automatically,)
  3. Follow the on-screen instructions to complete the setup.
tip

If you're using a non-official MQTT broker (such as EMQX Broker) instead of the standard Mosquitto broker, automatic discovery may not work. In this case, you'll need to manually enter the broker's IP address to establish the connection. This ensures that Home Assistant can communicate with your custom MQTT setup.

Add Users for MQTT Add-on​

When using the official Mosquitto Broker add-on in Home Assistant, you may need to set up credentials for the MQTT connection. This step ensures secure communication between your devices and Home Assistant. Here's how to add a user:

  1. Navigate to the Mosquitto broker add-on in your Home Assistant interface.
  2. Look for the "Users" section or tab within the add-on configuration.
  3. Click on the "Add User" or "+" button to create a new user.
Add User Button
Create User Form
  1. In the user creation form:
    • Enter a username of your choice. default is indicator-usrref.
    • Create a strong password. default is indicator-password.
    • Optionally, you can set specific permissions if needed.
  2. Save the new user credentials.
tip

Make sure to use these credentials when configuring your SenseCAP Indicator or any other MQTT devices to connect to Home Assistant.

After adding the user, you may need to restart the Mosquitto broker add-on for the changes to take effect. You should now be able to establish a secure MQTT connection using these credentials.

Remember to update your SenseCAP Indicator's MQTT settings with the new username and password to ensure it can communicate with Home Assistant.

Setting Up the SenseCAP Indicator ESP32 Project​

Before integrating your SenseCAP Indicator with Home Assistant, you need to set up the device with the appropriate firmware. Follow these steps to download, build, and flash the project to your SenseCAP Indicator.

Step 1: Download the Project​

There are two projects available for integrating SenseCAP Indicator with Home Assistant. Choose the one that best suits your needs:

This project is specifically designed for Home Assistant integration.

Get The Firmware

Or use Git to clone the repository:

git clone https://github.com/Love4yzp/sensecap-indicator-ha

Step 2: Navigate to the Project Directory​

Once you've downloaded or cloned the project, navigate to the appropriate directory:

cd sensecap-indicator-ha

Step 3: Build, Flash, and Monitor the Project​

Now you're ready to build the firmware, flash it to your SenseCAP Indicator, and monitor the device's output. Use the following command:

idf.py -p PORT build flash monitor

Replace PORT with the appropriate port for your device (e.g., COM3 on Windows or /dev/ttyUSB0 on Linux).

tip

If you're unsure about your device's port:

  • On Windows: Check Device Manager under "Ports (COM & LPT)"
  • On Linux/macOS: Run ls /dev/tty* in the terminal

This command will:

  1. Build the project
  2. Flash the firmware to your SenseCAP Indicator
  3. Open a serial monitor to display the device's output

To exit the serial monitor, press Ctrl-].

Step 4: Verify the Setup​

After flashing the firmware, the serial monitor will display output from your SenseCAP Indicator. Look for messages indicating successful connection to your Wi-Fi network and MQTT broker.

caution

Ensure that your SenseCAP Indicator is connected to the same network as your Home Assistant instance, and that your MQTT broker is properly configured and accessible.

Once you've successfully flashed and verified the firmware on your SenseCAP Indicator, you're ready to proceed with integrating it into Home Assistant using the MQTT integration.

Next, we'll configure Home Assistant to recognize and communicate with your SenseCAP Indicator.

Add MQTT Devices​

After setting up the MQTT integration in Home Assistant, the next step is to add MQTT devices. This process involves configuring Home Assistant to recognize and communicate with your SenseCAP Indicator Board through MQTT.

Step 1: Add Indicator Entities​

To add the SenseCAP Indicator entities to Home Assistant, you need to modify the configuration.yaml file. This file is crucial for defining how Home Assistant interacts with your devices.

tip

If you're using Home Assistant Yellow or any system with the File editor add-on, you can easily modify the configuration.yaml file through the web interface. For other setups, such as Home Assistant Container, you may need to modify the file via terminal access.

To modify the configuration.yaml file:

  1. Navigate to the File editor add-on in your Home Assistant dashboard.
  2. Select the configuration.yaml file from the file list.
  3. Add the following MQTT configuration to the file:
Click to expand and copy the MQTT configuration for SenseCAP Indicator
# SenseCAP Indicator MQTT Configuration
mqtt:
  sensor:
    - unique_id: indicator_temperature
      name: "Indicator Temperature"
      state_topic: "indicator/sensor"
      suggested_display_precision: 1
      unit_of_measurement: "°C"
      value_template: "{{ value_json.temp }}"
    - unique_id: indicator_humidity
      name: "Indicator Humidity"
      state_topic: "indicator/sensor"
      unit_of_measurement: "%"
      value_template: "{{ value_json.humidity }}"
    - unique_id: indicator_co2
      name: "Indicator CO2"
      state_topic: "indicator/sensor"
      unit_of_measurement: "ppm"
      value_template: "{{ value_json.co2 }}"
    - unique_id: indicator_tvoc
      name: "Indicator tVOC"
      state_topic: "indicator/sensor"
      unit_of_measurement: ""
      value_template: "{{ value_json.tvoc }}"
  switch:
    - unique_id: indicator_switch1
      name: "Indicator Switch1"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch1 }}"
      payload_on: '{"switch1":1}'
      payload_off: '{"switch1":0}'
      state_on: 1
      state_off: 0
    # ... (similar configurations for switches 2, 3, 4, 6, and 7)
  number:
    - unique_id: indicator_switch5
      name: "Indicator Switch5"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      command_template: '{"switch5": {{ value }} }'
      value_template: "{{ value_json.switch5 }}"
    - unique_id: indicator_switch8
      name: "Indicator Switch8"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      command_template: '{"switch8": {{ value }} }'
      value_template: "{{ value_json.switch8 }}"
  1. Save the changes to the configuration.yaml file.
caution

If your Home Assistant setup doesn't support add-ons (e.g., Home Assistant Container), you'll need to modify the configuration.yaml file through a terminal or SSH connection.

Step 2: Applying the Configuration Changes​

After modifying the configuration.yaml file, you need to apply the changes:

  1. Navigate to the Developer Tools in your Home Assistant dashboard.
  2. Find and click on the "YAML" tab.
  3. Reload configuration by ALL YAML CONFIGURATION.
YAML Configuration in Developer Tools
note

if something went wrong, you could

  • Click on the "Check Configuration" button to verify your changes.
  • If the configuration check passes, click on the "Restart" button to apply the new configuration.

After restarting, Home Assistant will recognize your SenseCAP Indicator entities, and you should be able to see them in your dashboard. If the entities don't appear immediately, you may need to wait a few minutes for the MQTT discovery process to complete.

Remember to ensure that your SenseCAP Indicator is properly configured to publish its data to the correct MQTT topics as defined in the configuration.

By following these steps, you've successfully added your SenseCAP Indicator devices to Home Assistant via MQTT. You can now use these entities in your automations, scripts, and dashboard for a more integrated smart home experience.

Set Up Dashboard​

The final step in integrating your SenseCAP Indicator with Home Assistant is to set up a custom dashboard. This will allow you to visualize and control your device's data and functions easily.

Creating a New Dashboard (Optional)​

If you want to create a dedicated dashboard for your SenseCAP Indicator:

  1. Navigate to Settings -> Dashboards in the Home Assistant sidebar.
  2. Click the "Add Dashboard" button.
  3. Set a title (e.g., "SenseCAP Indicator") and choose an icon.
  4. Click "Create" to finalize your new dashboard.
Create Dashboard
New Dashboard

Configuring the Dashboard​

To add SenseCAP Indicator entities to your dashboard:

  1. Open the dashboard you want to edit.
  2. Click the three-dot menu in the top right corner and select "Edit Dashboard".
  3. Click the "TAKE CONTROL" button to enable manual configuration.
Edit Dashboard
Take Control
  1. In the dashboard editor, click the three-dot menu again and select "Raw configuration editor".
  2. Replace the existing YAML content with the following configuration:
Click to copy Dashboard YAML to change the UI

Note: This is not for Configuration.YAML.

views:
  - title: Indicator device
    icon: ''
    badges: []
    cards:
      - graph: line
        type: sensor
        detail: 1
        icon: mdi:molecule-co2
        unit: ppm
        entity: sensor.indicator_co2
      - graph: line
        type: sensor
        entity: sensor.indicator_temperature
        detail: 1
        icon: mdi:coolant-temperature
      - graph: line
        type: sensor
        detail: 1
        entity: sensor.indicator_humidity
      - graph: line
        type: sensor
        entity: sensor.indicator_tvoc
        detail: 1
        icon: mdi:air-filter
      - type: entities
        entities:
          - entity: switch.indicator_switch1
          - entity: switch.indicator_switch2
          - entity: switch.indicator_switch3
          - entity: switch.indicator_switch4
          - entity: number.indicator_switch5
          - entity: switch.indicator_switch6
          - entity: switch.indicator_switch7
          - entity: number.indicator_switch8
        title: Indicator control
        show_header_toggle: false
        state_color: true
caution

This YAML configuration is specifically for the dashboard and should not be added to your configuration.yaml file.

  1. Click "SAVE" to apply the changes.
Raw Configuration Editor
Save Configuration

Congratulations! You've successfully configured your Home Assistant dashboard to display and control your SenseCAP Indicator. You can now monitor CO2 levels, temperature, humidity, and TVOC, as well as control various switches directly from your Home Assistant interface.

Resources​

  1. Demo SDK: The Demo SDK for the SenseCAP Indicator is available on GitHub.
  2. indicator_ha.c File: This file contains the main functions for the Home Assistant integration. You can view it here.
  3. User Guide: The User Guide provides detailed information about the software and hardware of the SenseCAP Indicator Board. You can read it here.
  4. Home Assistant Installation Guide: If you're new to Home Assistant, this guide will help you get it installed and set up. You can find it here.
  5. Getting Started Guide for ESP-IDF: This guide provides full steps to configure and use ESP-IDF to build projects. You can access it here.
  6. Home Assistant Concepts and terminology

Reference​

Tech Support​

Need help with your SenseCAP Indicator? We're here to assist you!

If you encounter any issues or have any questions while following this tutorial, please feel free to reach out to our tech support. We are always here to help!

Visit our Seeed Official Discord Channel to ask your questions or the GitHub discussions to share all you want!

  1. MQTT default credential - GitHub↩
Loading Comments...