UART

The UART API enables serial communication with external devices through the UART interface. This is useful for integrating with sensors, displays, and other serial devices.

Device Support

UART functionality requires specific hardware support and configuration. Not all Shelly devices have accessible UART pins. Check your device specifications before attempting to use UART.

Overview

UART (Universal Asynchronous Receiver/Transmitter) provides serial communication between your Shelly device and external hardware. Common use cases include:

• Reading data from serial sensors
• Controlling serial displays
• Communicating with Arduino/ESP devices
• Integrating legacy serial equipment

Getting Started

// Get UART instance
let uart = UART.get(0); // Get UART interface 0

// Configure UART
uart.configure({
  baud: 9600,
  format: "8N1"
});

// Send data
uart.send("Hello Serial World!\r\n");

// Receive data
uart.recv(function(data) {
  console.log("Received:", data);
});

API Reference

UART.get(id)

Get a handle to a UART interface.

Parameters:

• id (number): UART interface ID (typically 0)

Returns: UART instance or null if not available

Example:

let uart = UART.get(0);
if (!uart) {
  console.log("UART not available on this device");
}

UART Instance Methods

configure(options)

Apply UART configuration: baud rate and serial mode. Throws if the requested config values are invalid.

Parameters:

• options (object): Configuration object with the following properties:
  • baud (number, optional): The baud rate to use, default is device-specific
  • format (string, optional): 3-character string denoting data bits (7, 8 or 9), parity (N, E or O) and stop bits (1 or 2). Default is "8N1"

Example:

uart.configure({
  baud: 115200,
  format: "8N1"
});

send(data)

Send data over UART.

Parameters:

• data (string): Data to send

Returns: Number of bytes sent

Example:

let bytesSent = uart.send("AT+STATUS\r\n");
console.log("Sent", bytesSent, "bytes");

recv(callback)

Set up a callback to receive data.

Parameters:

• callback (function): Function called when data is received
  • Receives data (string) parameter

Example:

uart.recv(function(data) {
  console.log("Received:", data);
  
  // Parse received data
  if (data.indexOf("OK") >= 0) {
    console.log("Command successful");
  }
});

Complete Example

Serial Sensor Reader

// Read data from a serial sensor every second

let uart = UART.get(0);

if (!uart) {
  console.log("UART not available");
} else {
  // Configure for common sensor settings
  uart.configure({
    baud: 9600,
    format: "8N1"
  });
  
  // Buffer for incoming data
  let buffer = "";
  
  // Set up receiver
  uart.recv(function(data) {
    buffer += data;
    
    // Check for complete message (ending with newline)
    let lines = buffer.split("\n");
    
    // Process complete lines
    for (let i = 0; i < lines.length - 1; i++) {
      processSerialData(lines[i].trim());
    }
    
    // Keep incomplete line in buffer
    buffer = lines[lines.length - 1];
  });
  
  // Request data periodically
  Timer.set(1000, true, function() {
    uart.send("READ\r\n");
  });
}

function processSerialData(line) {
  console.log("Sensor data:", line);
  
  // Parse sensor data (example: "TEMP:25.5,HUM:60")
  let parts = line.split(",");
  for (let part of parts) {
    let [key, value] = part.split(":");
    if (key === "TEMP") {
      handleTemperature(parseFloat(value));
    } else if (key === "HUM") {
      handleHumidity(parseFloat(value));
    }
  }
}

function handleTemperature(temp) {
  if (temp > 30) {
    // Turn on cooling
    Shelly.call("Switch.Set", {id: 0, on: true});
  }
}

function handleHumidity(humidity) {
  console.log("Humidity:", humidity, "%");
}