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.

Connectors¶

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¶