Skip to main content

Use a remote UART with a local tool

mimick uart tunnel opens a local TCP port that carries a bench's UART. Any tool that speaks RFC 2217 (Telnet COM-Port Control) can then flash, reset, and talk to the DUT from your workstation, with no MIMICK code in the tool. pyserial, and the tools built on it such as esptool, open the port with an rfc2217:// URL.

The tool can change the baud rate, parity, and data and stop bits, drive DTR and RTS, send a break, and read CTS, DSR, RI, and DCD, all through the tunnel.

What you need​

  • Operator access to the bench
  • A serial port (linux-tty with a tty interface, or an FTDI UART) wired to your DUT
  • An active bench (mimick bench use <your-bench>)

Find the uart location with mimick peripheral list. It ends in .uart0.

Start the tunnel​

mimick uart <location> tunnel 7000

The command listens on 127.0.0.1:7000 and runs until you press Ctrl-C. Pass --bind to listen on another address. It serves one client at a time and refuses a second connection until the first one leaves.

The bench's UART is held only while a client is connected. While it is held, a runbook, mimick connect, or another tunnel that tries to use the same UART gets a busy error.

Open the port from a tool​

Use the tunnel's address as an rfc2217:// URL:

import serial

port = serial.serial_for_url("rfc2217://127.0.0.1:7000", baudrate=115200)
port.write(b"version\r\n")
print(port.read(64))
port.dtr = False   # drives DTR on the bench
port.baudrate = 9600

Other tools take the same URL as their port:

esptool --port rfc2217://127.0.0.1:7000 chip-id

Tools that open only a device path can use socat to create one:

socat pty,link=/tmp/bench-uart,raw tcp:127.0.0.1:7000

A pty has no modem lines, so DTR and RTS do not pass through it, and the tunnel's RFC 2217 control codes reach the tool as data. Use --raw for this case.

Set the starting state​

The tunnel applies these flags each time a client connects:

mimick uart <location> tunnel 7000 --baud 921600 --parity even --dtr off --rts off

--baud, --data-bits, --parity, and --stop-bits set the line settings, and --dtr and --rts set the starting level of the lines. A flag you leave out keeps the value the port has.

Serve a plain byte stream​

mimick uart <location> tunnel 7000 --raw

--raw skips the Telnet framing, so a tool that only opens a TCP socket reads and writes the UART's bytes directly. A raw client can't change the line settings or drive the lines; set them with the flags above.

Limits​

  • A client's change to flow control is refused. Set flow_control in the peripheral config.
  • A client's break lasts 250 ms, whatever its break-off request says.
  • Mark and space parity aren't available.
  • The session ends when your tool closes its side of the connection. A shell pipe that closes stdin at once can end the session before the reply comes back, so keep the pipe open, as in (echo hi; sleep 1) | socat - tcp:127.0.0.1:7000.
  • The Cloud closes a tunnel that carries no traffic in either direction for two minutes. Start it again.
  • The tunnel needs a bench that runs a release with UART streaming. An older bench doesn't answer, and the command reports that after 10 seconds.

If a command fails​

What you seeWhat to do
cannot open the UART: another session ... is using itClose the other tunnel, console, or runbook that holds the UART, then reconnect.
listen on ...: address already in usePick another local port.
this port has no tty interfaceAsk your org admin to add a tty interface to the port.
cannot open the UART: the Station did not answerThe Station runs an older release that can't stream a UART. Update it, then try again.
the bench "<name>" is offlineCheck that the bench has power and a network connection.
A permission errorAsk your org admin for the Operator grant on the bench.
the call stopped making progressThe tunnel carried no traffic in either direction for two minutes, so the Cloud closed it. Start the tunnel again. Any session over it that ends this way ends the same.