Serial

The Serial integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] uses the data provided by a device connected to a serial port that Home Assistant can reach. The port can be on the system where Home Assistant runs, or shared over your network. To connect a device that is not next to your system, the recommended way is a serial proxy, which shares a serial port from an ESPHome device over your network. You can also use ser2net or socat to reach a device on a remote system.

To check what kind of data is arriving at your serial port, use a serial terminal program. On Linux, use minicom or picocom. On macOS, use screen. On Windows, use PuTTY.

sudo minicom -D /dev/ttyACM0

Configuration

To set up a serial sensor to your installation, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file. After changing the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes. The integration is now shown on the integrations page under Settings > Devices & services. Its entities are listed on the integration card itself and on the Entities tab.

# Example configuration.yaml entry
sensor:
  - platform: serial
    serial_port: /dev/ttyACM0

About serial terminology

This section explains some of the key terms that the Home Assistant documentation uses to describe serial connections.

Serial port

An interface that sends data sequentially, one bit at a time. A serial port can be built into your system, added with a USB-to-serial adapter, or shared over your network by a serial proxy.

Device path

The identifier that Home Assistant uses to address a serial port, such as /dev/ttyACM0. This is the value you enter for the serial_port option. A serial port that is reached over the network is addressed with a URL instead of a device path, such as socket://192.168.1.10:4001 for a port that you expose with ser2net. The URL of a port that is shared by a serial proxy starts with esphome-hass://.

For local serial ports, always use the /dev/serial/by-id/... link instead of paths like /dev/ttyUSB0 and /dev/ttyACM0. The by-id link is stable and will not change even when you move ports around or move HA OS to another device. The /dev/tty links are not stable and can be renumbered.

Serial proxy

The recommended way to connect a serial device to Home Assistant. A serial proxy is an ESPHome device that uses the serial proxy component to share one of its serial ports over your network, so that Home Assistant can use that port as if it were connected to your system. The serial port that it shares is what you select in Home Assistant.

Because the proxy connects over the network, you can place it close to the end device, no matter where it is located. Prefer a wired network connection to the proxy.

USB-to-serial adapter

A device that adds a serial port to your system over USB. Use a USB-to-serial adapter when the end device is close enough to cable directly to the system that runs Home Assistant. If it isn’t, use a serial proxy instead.

“Serial” is a broad label that can mean RS-232, RS-422, RS-485, or TTL-serial. An adapter for a device with an RS-232 port is also sold as a USB-to-RS-232 adapter.

Baud rate

The speed of a serial connection, in bits per second. Home Assistant and the connected device must use the same baud rate, otherwise the data arrives unreadable. Common values are 9600 and 115200. Check the documentation of your device for the value that it uses.

RS-232

A standard for serial connections that is common on devices such as receivers, projectors, and TVs. To use a device with an RS-232 port, you typically connect it with a USB-to-serial adapter or a serial proxy.

value_template for Template sensor

TMP36

"{{ (((states('sensor.serial_sensor') | float * 5 / 1024 ) - 0.5) * 100) | round(1) }}"

Finding the device path of a serial port

To find the device path to use for the serial_port option, go to Settings > Connectivity > Serial. Next to your port, select Port information and copy the Device field. For more details about this panel, refer to Viewing your serial ports.

If a serial port is detected by Home Assistant but is used only by serial sensors configured in your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more], it is not tracked as having a consumer. As a result, it appears in the Available section of the panel rather than the Connected section.

Examples

Arduino

For controllers of the Arduino family, a possible sketch to read the temperature and the humidity could look like the sample below.The returned data is in JSON format and can be split into the individual sensor values using a template.

#include <ArduinoJson.h>

void setup() {
  Serial.begin(115200);
}

void loop() {
  StaticJsonDocument<100> jsonBuffer;

  jsonBuffer["temperature"] = analogRead(A0);
  jsonBuffer["humidity"] = analogRead(A1);

  serializeJson(jsonBuffer, Serial);
  Serial.println();
  
  delay(1000);
}

Devices returning multiple sensors as a text string

For devices that return multiple sensors as a concatenated string of values with a delimiter (that is, the returned string is not JSON formatted) you can make several template sensors, all using the same serial response. For example, a stream from the Sparkfun USB Weather Board includes temperature, humidity and barometric pressure within it returned text string. Sample returned data:

$,24.1,50,12.9,1029.83,0.0,0.00,*
$,24.3,51,12.8,1029.76,0.0,0.00,*

To parse this into individual sensors, split using the comma delimiter and then create a template sensor for each item of interest.

# Example configuration.yaml entry
sensor:
  - platform: serial
    serial_port: /dev/ttyUSB0
    baudrate: 9600

template:
  sensor:
    - name: Temperature
      unit_of_measurement: "°C"
      state: "{{ states('sensor.serial_sensor').split(',')[1] | float(default=0) }}"
    - name: Humidity
      unit_of_measurement: "%"
      state: "{{ states('sensor.serial_sensor').split(',')[2] | float(default=0) }}"
    - name: Barometer
      unit_of_measurement: "mbar"
      state: "{{ states('sensor.serial_sensor').split(',')[4] | float(default=0) }}"

Digispark USB Development Board

This blog post describes the setup with a Digispark USB Development Board.