Raw Serial

Warning

The Raw Serial integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] reads raw text from a serial port. To get useful values, you usually need to process that text with templates. Most devices with a serial port already have an integration that handles the connection for you. Before you use this integration, search the integrations for your device or its brand.

The Raw 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, for example by a serial proxy.

This page documents the Raw Serial integration. To learn more about serial connections in Home Assistant, refer to Serial.

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

Raw Serial sensor

The Raw 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 Raw 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

Configuration Variables

serial_port string Required

The device path of the serial port to read from. Use the /dev/serial/by-id/... link where one is available. Avoid paths like /dev/ttyUSB0 and /dev/ttyACM0 because their mappings can change; in other words, which device appears as ttyACM0 will vary. For a port that Home Assistant reaches over your network, use its URL instead, such as socket://192.168.1.10:4001.

name string (Optional, default: Serial Sensor)

Name of the sensor.

baudrate integer (Optional, default: 9600)

The baud rate of the serial port, in bits per second.

bytesize integer (Optional, default: 8)

Number of data bits. Possible values: 5, 6, 7, 8.

parity string (Optional, default: N)

Parity checking. Possible values: N (none), E (even), O (odd), M (mark), S (space).

stopbits float (Optional, default: 1)

Number of stop bits. Possible values: 1, 1.5, 2.

xonxoff boolean (Optional, default: false)

Enable software flow control.

rtscts boolean (Optional, default: false)

Enable hardware (RTS/CTS) flow control.

dsrdtr boolean (Optional, default: false)

Enable hardware (DSR/DTR) flow control.

value_template template (Optional)

Defines a template to extract a value from the serial line.

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

For problems with the serial connection itself, such as a port that is not listed or a device that does not respond, refer to Troubleshooting serial connections.