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

Setting up a serial connection in Home Assistant

You can connect a device connected via serial to the system running Home Assistant, or access it over your network with a serial proxy.

Prerequisites

• Administrator rights in Home Assistant.
• A serial-connected device, such as an AV receiver, a projector, or a smart meter with a P1 port.
• An integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] for that device. In the documentation, search the integrations for your device or its brand.
  • If no integration is available for your device, you can read the raw data from the port with the Serial sensor instead.
• A way for Home Assistant to reach the serial port of that device:
  • A USB-to-serial adapter, if the device is close enough to cable it to the system that runs Home Assistant.
  • A serial proxy, if it is not. Because the proxy connects over your network, you can place it next to the device. To choose one and prepare it, refer to Setting up an ESPHome serial proxy.
  • A serial device server, if you already have one on your network.
• The connection settings that your device expects, such as the baud rate. Check the documentation of your device.

To set up a serial connection in Home Assistant

1. Connect your device to a serial port that Home Assistant can reach.
   • USB-to-serial adapter: connect your device to the adapter, then plug the adapter into the system that runs Home Assistant.
   • Serial proxy: connect your device to one of the serial ports of the ESPHome device. Then, add the ESPHome integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more]. The serial ports that the ESPHome device shares become available to Home Assistant. If you do not have a serial proxy yet, first refer to Setting up an ESPHome serial proxy.
   • Serial device server: connect your device to one of the serial ports of the device server. On the device server, share that port on a TCP port, and set the baud rate and the other connection settings that your device expects. The URL of the port is made of the IP address of the device server and that TCP port, such as socket://192.168.1.10:4001. You need this URL in step 3. The port is not listed in the Serial panel before then, so you can skip step 2.
2. Optional: check if Home Assistant sees the port. Go to Settings > Connectivity > Serial.
   • A port is listed as soon as its adapter or serial proxy is available, whether or not your device is wired to it yet.
   • A port that a serial proxy shares is listed only while the ESPHome device is online.
   • If your port is not listed, select Refresh in the top right corner.
   • For more details, refer to Viewing your serial ports.
3. Add the integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] for your device, such as Denon RS-232.
   • To add the integration, follow the steps in the integration documentation.
   • When you are asked which serial port to use, select the port that your device is connected to. Local ports and serial proxy ports are listed together, grouped by type. Ports that suit the integration you are setting up are listed first, under Recommended for the integration. When you select a port, Home Assistant stores the most stable identifier that is available for it.
   • A port that is shared by a serial proxy is listed under Serial proxies, together with the name of the ESPHome device that shares it.
   • If you enter a local device path yourself, use the /dev/serial/by-id/... link rather than a path like /dev/ttyUSB0 or /dev/ttyACM0, because their mappings can change; in other words, which device appears as ttyACM0 will vary. To look up the link, select Port information for that port in the Serial panel, and copy the Device field.
   • The list shows the ports that Home Assistant found on your system and on your serial proxies. A port on another system, such as one that you expose with ser2net or socat, is not found automatically. To use such a port, select Enter manually and enter its URL, such as socket://192.168.1.10:4001. For more details, refer to Device path.

Setting up an ESPHome serial proxy

A serial proxy shares one of its serial ports with Home Assistant over your network. ESPHome is currently the only integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] that provides serial proxy ports.

To set up an ESPHome serial proxy

1. Choose a device that runs ESPHome and has a free serial port.
   • Make sure the port type matches the device you want to connect: TTL, RS-232, or RS-485.
   • To find a device, refer to the ESPHome device database.
   • An ESPHome device can proxy more than serial. For an overview, refer to ESPHome remote adapters (proxies).
2. Install the serial proxy configuration on the ESPHome device.
   • For some devices, there is a ready-made project that you can install from your browser. To see what is available, refer to the ESPHome serial proxy projects.
   • If no ready-made project fits your device, add the serial proxy component to the configuration of your ESPHome device yourself.
   • The integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] that uses a port sets the baud rate and the other connection settings when it connects. This means you do not need to change the ESPHome configuration when a device needs a different baud rate.
3. Continue with Setting up a serial connection in Home Assistant. There, you connect your device to the proxy, add the ESPHome integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more], and select the shared port.

Serial sensor

The Serial sensor reads the raw data from a serial port and makes it available as a sensor entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more]. Use it when no integration is available for your device.

To add a serial sensor, 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 or a serial device server.

Device path

The identifier that Home Assistant uses to address a serial port. This is the value you enter for the serial_port option.

For a serial port exposed via USB, use the /dev/serial/by-id/... path when available. This path stays the same as you move the device to another USB port or move your Home Assistant installation to another system. Avoid paths like /dev/ttyUSB0 and /dev/ttyACM0 because their mappings can change; in other words, which device appears as ttyACM0 will vary. If there is no by-id link (for example, for a built-in port), use a path like /dev/ttyS0. A serial port connected over the network is identified by a URL instead, 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://.

Serial proxy

A remote adapter that shares a serial port with Home Assistant over your network. A serial proxy is an ESPHome device that uses the serial proxy component to share one or more of its serial ports, so that Home Assistant can use them as if they were connected to your system. When an integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] asks you to select a serial port, the shared ports are listed next to the ports of your own system. The port that the proxy shares is what you select in Home Assistant.

A serial proxy is the recommended way to connect a device connected via serial that is not next to the system running Home Assistant. A direct serial cable only reaches so far, and it ties your device to the place where your system is. With a serial proxy, you place the ESPHome device next to your device instead, and your network covers the rest of the distance. Prefer a wired network connection to the proxy.

To choose and prepare a serial proxy, refer to Setting up an ESPHome serial 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 device connected via serial 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.

Serial device server

Another way to put a serial port on your network, without using a serial proxy. This can be a piece of hardware with one or more serial ports, or another computer on your network that shares a port with ser2net or socat.

Home Assistant uses such a port differently from a serial proxy:

• Home Assistant does not find the port by itself. The port is listed in the Serial panel only after an integration that you added in the UI uses it. It is then listed under Connected, even while the device server is offline, because Home Assistant cannot check it. A port that is only used by a Serial sensor 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], or only by Modbus, is not listed.
• With a socket:// URL, Home Assistant sends and receives only data. The baud rate and the other connection settings of the integration are not passed on, so set them on the device server itself. If your device server supports RFC 2217, you can use an rfc2217:// URL instead. Home Assistant then passes these settings on to the device server.

To use the port with an integration, select Enter manually during integration setup and enter its URL, such as socket://192.168.1.10:4001. For more details, refer to Device path.

Device connected via serial

The device you want to use with Home Assistant, such as an AV receiver, a projector, or a smart meter with a P1 port. It communicates over a serial connection instead of over your network, so Home Assistant reaches it through a serial port.

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], or only by Modbus, 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.

Troubleshooting