Serial devices (UART)¶

On the program side, machine.UART produces a real electrical frame on two microcontroller pins (API). At the other end of the wire, Peripherals provides five serial devices: they decode what they receive, bit by bit, and reply with a real frame in turn.

Voltage of the transmit pin (mcu.GP0.v) in the Uart.Loopback example: start bit at 0, 8 data bits (least significant first), stop bit at 1. Figure labels are in French: « temps » = time, « bits de poids faible en tête » = least significant bits first.

Wiring¶

Two crossed wires and a common ground, as on a real board:

from machine import Pin, UART
import time

uart = UART(0, baudrate=1200, tx=Pin(5), rx=Pin(4))
uart.write(b'AT+TEMP\n')
time.sleep_ms(200)              # give the reply time to arrive
if uart.any():
    print(uart.readline())      # b'TEMP=21.5\r\n'

Reception does not wake the program up: it polls the link with any(), read() or readline().

Supplied devices¶

They all share the same connectors and parameters; they only differ by their defaults and their icon. The only exception, UartLcd20x2 shows only the frame format (baudrate, dataBits, parity, stopBits) and the Electrical tab: its other settings are fixed, and it has neither a TX pin nor a valueOut connector (it transmits nothing and returns nothing to the model).

Connectors¶

On the program side, the link is written with machine.UART: see the API and the official MicroPython documentation (machine.UART, rp2 port).

Frame format¶

The device uses its own format, set by dataBits, parity and stopBits (8N1 by default) and shown on its icon (1200,N,8,1, 1200,E,8,2…). It must be the one the program passes to UART(...):

uart = UART(0, baudrate=1200, bits=8, parity=0, stop=2, tx=Pin(5), rx=Pin(4))   # device: parity = Even, stopBits = 2

On a mismatch, the device and the microcontroller keep the bytes received with an error but report them in the log (parity error, framing error; the first ten, then a total at the end of the simulation). A parity mismatch lets correct bytes through, merely reported; a baud rate or data-bit mismatch gives wrong bytes. The Uart.Format and Uart.FormatMismatch examples show both situations.

Parameters¶

Behaviour and link (General tab)¶

Command table (Table tab, Table mode)¶

Inputs / outputs (Inputs / outputs tab)¶

Electrical (Electrical tab)¶

Describing the device with a table¶

A single string describes all commands: "CMD=>REPLY|CMD=>REPLY". The characters | and => are reserved. A command is recognised when the complete received line (without its terminator) is identical to it.

commandTable = "AT+TEMP=>TEMP={v1:.1f}\r\n|AT+ID=>SIM-TEMP-1\r\n|SET {o1}=>OK\r\n"

With this table, the program reads the temperature over the serial link and sends back a command over the same link. valueOut[1] passes it to the rest of the model: this is what the Uart.Regulation example does, a complete control loop through the two wires of the link alone.

Legend: « mesure » = measurement, « commande reçue par SET » = command received through SET, « consigne » = setpoint.

Describing the device with a Python script¶

With behaviour = Script, the scriptPath file replaces the table. It defines up to three functions, all optional:

state = 'STOPPED'       # module variables: the device state,
readings = 0            # which persists from one call to the next

def on_receive(line, t, v):         # once per complete received line
    global state, readings
    if line == b'START':
        state = 'RUNNING'
        return b'OK\r\n'
    if line == b'READ' and state == 'RUNNING':
        readings += 1
        return 'VAL=%.2f N=%d\r\n' % (v[0], readings)
    return b'ERR\r\n'

def on_tick(t, v):                  # every `period` seconds, if defined
    return None

def outputs():                      # read after each call -> valueOut
    return (1.0 if state == 'RUNNING' else 0.0, readings)

Rules to know:

• The script is loaded once per device: two devices using the same file each have their own variables.
• Each line is delivered only once, even if the simulation re-evaluates the same instant several times: a state machine never replays its transitions.
• Functions must return without waiting: no sleep() (responseDelay delays a reply), no machine nor time, which belong to the microcontroller. The file must be self-contained (no import of neighbouring files).
• print() goes to the log, prefixed with the device name. An exception stops the simulation.

Starting point: copy Resources/Scripts/Device/generic.py. Examples: Uart.EchoPy, Uart.GpsPy, Uart.StateMachinePy.

Variables to plot¶

Looping the link back onto the microcontroller¶

To watch the frame of an MCU alone, without a device, connect its TX pin to its RX pin. Not with a plain wire: a direct connect() between two pins of the same MCU makes the driven voltage disappear from the results. Go through a 1 kΩ resistor, with a 1 nF capacitor from the RX pin to ground, as in the Uart.Loopback example; the frame is not distorted (time constant ≈ 1 µs, for 833 µs bits at 1200 baud).

Examples¶