mimick-hwi

The mimick-hwi driver talks to the MIMICK HWI hardware interface boards, which switch DUT power, reset, and boot mode. The driver exposes the board's GPIO pins, and can present any of them as a relay channel. On an HWI v2 it also serves the DUT console.

The mode key in the gpio interface's config picks the board generation:

Property	HWI v1	HWI v2
`kind`	`mimick-hwi`	`mimick-hwi`
`mode`	Leave it out, or `v1`	`v2`
Interfaces	`gpio`, `relay`	`gpio`, `relay`, `uart`, `tty`
`location`	The board controller's `/dev/serial/by-id/` path	`usb:0403:6010@<usb_path>`, the board's USB port

HWI v1

One board, four peripherals

The HWI board is a USB hub with four devices behind it, and each one is its own peripheral in the file:

Device	Driver
ESP32-S3 GPIO controller	`mimick-hwi`
CP2104 USB-to-UART bridge (×2)	`linux-tty`
FT232R USB-to-UART bridge	`linux-tty`

There's no entry for the hub itself. mimick peripheral list shows the four devices as separate rows. Paste the ESP32's path into the mimick-hwi entry and each bridge's path into its own linux-tty entry.

Example

hwi:
  kind: mimick-hwi
  name: "MIMICK HWI"
  description: "Hardware interface board for DUT power, reset and muxing"
  location: /dev/serial/by-id/usb-Espressif_USB_JTAG_serial_debug_unit_F0:F5:BD:7B:5C:D0-if00
  interfaces:
    - type: gpio
      channel: 0
      config:
        pins:
          # ESP32 bank
          - { pin: 0, name: "Boot", direction: input }
          - { pin: 1, name: "ADC MUX 0", direction: output }
          - { pin: 2, name: "LED", direction: output }
          - { pin: 4, name: "USB MUX 0", direction: output }
          - { pin: 5, name: "USB MUX 1", direction: output }
          - { pin: 6, name: "USB MUX 2", direction: output }
          - { pin: 7, name: "USB MUX 3", direction: output }
          - { pin: 10, name: "Eth MUX 0", direction: output }
          - { pin: 11, name: "Eth MUX 1", direction: output }
          - { pin: 12, name: "Eth MUX 2", direction: output }
          - { pin: 14, name: "Flash Mode", direction: output }
          - { pin: 15, name: "DUT Reset", direction: output }
          - { pin: 16, name: "ALT Boot", direction: output }
          - { pin: 17, name: "ADC MUX 1", direction: output }
          - { pin: 18, name: "DUT Power", direction: output }
          # MCP23017 expander bank
          - { pin: 32, name: "Alt Boot", direction: output }
          - { pin: 33, name: "PMIC On Req", direction: output }
          - { pin: 34, name: "PMIC Standby Req", direction: output }
          - { pin: 35, name: "Power Button", direction: output }
          - { pin: 39, name: "Expander DUT Reset", direction: output }
          - { pin: 44, name: "I2C MUX", direction: output }

dut_console:
  kind: linux-tty
  name: "DUT console"
  description: "CP2104 on the HWI hub"
  location: /dev/serial/by-id/usb-Silicon_Labs_CP2104_USB_to_UART_Bridge_Controller_02D881C5-if00-port0
  interfaces:
    - type: uart
      channel: 0
      config: { baud_rate: 115200, parity: none, stop_bits: 1 }
    - type: tty
      channel: 0
      config: { cols: 80, rows: 24 }
      backed_by: { type: uart, channel: 0 }

The names in this example match the reference board's wiring. The driver doesn't know what each pin connects to, so change the names to match your board.

GPIO

The gpio interface is required, on channel 0. It takes an optional pins list, and every key in an entry is optional:

Key	Default	Allowed values	Effect
`pin`		See Pin banks	The pin this entry configures.
`name`	Chip name, such as `GPIO15` or `MCP7`	Any label	Shown in the CLI and web UI, and accepted in place of the number.
`direction`		`input` or `output`	A label only. The firmware sets each pin's direction at boot.
`active_level`	`high`	`high` or `low`	Inverts the pin's logical level when set to `low`, for reads and writes.

A pin you leave out of the list is still readable and writable under its chip name.

Pin banks

The board has two banks of pins in one numbering scheme:

Bank	Pins	Notes
ESP32	0, 1, 2, 4, 5, 6, 7, 10, 11, 12, 14, 15, 16, 17, 18	The ESP32's own GPIO numbers. Other numbers aren't exposed.
MCP23017 expander	32 to 47	Expander pins 0 to 15. All are outputs.

A pin number outside these lists is an error.

The firmware sets each pin's direction and boot level. On the reference board, pin 0 is an input and every other pin is an output. These pins boot high, and the rest boot low:

ESP32 bank: 0, 14, 15, 16, 18
Expander bank: 32, 33, 34, 36, 37, 38, 39

Limits

Outputs are push-pull only. The board doesn't support open-drain or open-source outputs, or setting drive strength.
The board can't release its pins to high impedance.
A write to a pin the firmware set as an input succeeds but has no effect.

Relay

Add a relay interface to treat output pins as on/off relay channels. The channels follow the same format as other relay drivers, except each path names a GPIO pin on the same board:

hwi:
  kind: mimick-hwi
  name: "MIMICK HWI"
  location: /dev/serial/by-id/usb-Espressif_USB_JTAG_serial_debug_unit_F0:F5:BD:7B:5C:D0-if00
  interfaces:
    - type: relay
      channel: 0
      config:
        channels:
          - { number: 1, name: "Power Button", path: "GPIO:Power Button" }
          - { number: 2, name: "Alt Boot", path: "GPIO:32" }
    - type: gpio
      channel: 0
      config:
        pins:
          - { pin: 32, name: "Alt Boot", direction: output }
          - { pin: 35, name: "Power Button", direction: output }

Key	Required	Effect
`number`	Yes	The channel number, starting at 1. Unique within the interface.
`name`	No	Shown in the CLI and web UI. Defaults to the pin's name.
`path`	Yes	`GPIO:` followed by the pin's `name` or its number.

A relay channel is on while its pin is at the pin's active level, so active_level: low on the pin makes the channel drive the pin low when on.

The pin must be listed under the gpio interface's pins, and it can't be declared as an input. Two channels can't share a pin. The relay's names and the GPIO's names are separate, so a channel can share a name with a pin.

A peripheral with more than one interface needs the interface in its address. Once you add the relay interface, use -p hwi.gpio0 for GPIO commands and -p hwi.relay0 for relay commands.

Use it

mimick gpio list -p hwi.gpio0
mimick gpio write -p hwi.gpio0 "DUT Power" off
mimick gpio read -p hwi.gpio0 Boot
mimick relay write -p hwi.relay0 "Power Button" on

In the web UI, select Open GPIO controls on the peripheral's row in the bench's Inventory tab.

HWI v2

The HWI v2 is a single FTDI FT2232H USB chip. Channel A (0) is your DUT's console, and channel B (1) talks to the board's controller, which drives 13 GPIO pins. One mimick-hwi entry covers the whole board, so don't declare the same chip as ftdi-ft232h as well.

Location

The chip has no serial number, so you address it by the USB port it's plugged into: usb:0403:6010@<usb_path>. mimick peripheral list shows the board as an ftdi-ft232h row until you declare it, with a location you can paste.

Example

hwi_v2:
  kind: mimick-hwi
  name: "HWI V2"
  description: "HWI v2 with the DUT console on A and the HWI controller on B"
  location: usb:0403:6010@1-2.1
  interfaces:
    - type: uart
      channel: 0
      config: { baud_rate: 115200 }
    - type: tty
      channel: 0
      config: { cols: 80, rows: 24 }
      backed_by: { type: uart, channel: 0 }
    - type: gpio
      channel: 1
      config:
        mode: v2
        pins:
          - { pin: 4, name: "DUT Reset", direction: output, initial: high, drive_mode: open_drain }
          - { pin: 5, name: "Boot Sel", direction: input, pull: up, active_level: low }
          - { pin: 0, name: "Power Button", direction: output }
    - type: relay
      channel: 1
      config:
        channels:
          - { number: 1, name: "Power Button", path: "GPIO:Power Button" }

Interface	Channel	Required	Notes
`gpio`	`1`	Yes	Set `mode: v2`.
`relay`	`1`	No	Works as on the HWI v1. See Relay.
`uart`	`0`	No	The DUT console. Takes the same keys as an `ftdi-ft232h` UART.
`tty`	`0`	No	An interactive terminal over the console. Needs `backed_by: { type: uart, channel: 0 }`.

Pins

Each entry under pins configures one of pins 0 to 12:

Key	Default	Allowed values	Effect
`pin`		`0` to `12`	The pin this entry configures.
`name`	The controller's pin name, such as `PB13`	Any label	Shown in the CLI and web UI, and accepted in place of the number.
`direction`	Required	`input` or `output`	Sets the pin's direction on the board.
`active_level`	`high`	`high` or `low`	Inverts the pin's logical level when set to `low`, for reads and writes.
`drive_mode`	`push_pull`	`push_pull` or `open_drain`	Outputs only.
`pull`	`none`	`none`, `up`, or `down`	Turns on the board's internal pull resistor.
`speed`	`low`	`low`, `medium`, `fast`, `high`	The output's edge speed.
`initial`	`low`	`low` or `high`	Outputs only. The level at power-up and whenever the bench opens the board.
`report_changes`	`true`	`true` or `false`	Inputs only. When `true`, the board reports changes instead of being polled.

A pin you leave out is unused: it floats at high impedance and isn't shown in the web UI. mimick gpio list --all still lists it.

The bench saves your pin settings to the board, so if the board restarts on its own, its outputs come back at their initial levels.

Some pins can't take every setting. The board rejects the setting and the bench reports the peripheral as absent, with the pin named in the reason:

Pins 0 to 3 don't accept active_level: low.
Pin 1 only accepts speed: low.
Pin 2 doesn't accept drive_mode: open_drain.

caution

Pins 0, 1, and 3 drive a transistor that pulls the connector line low when the pin is at logical 1. Pin 2 drives its line to about 3.0 V at logical 1 and releases it at 0. Name these pins for what they do to your DUT.

Limits

Outputs are push-pull or open-drain. The board doesn't support open-source outputs or setting drive strength.
Pin settings you change at runtime with mimick gpio config last until the bench reopens the board, which restores the settings in the file.
Writing to a pin that isn't an output fails, and no pin in that write changes.

Use it

With the relay interface declared, the GPIO is on channel 1:

mimick gpio list -p hwi_v2.gpio1
mimick gpio write -p hwi_v2.gpio1 "DUT Reset" off
mimick gpio watch -p hwi_v2.gpio1 "Boot Sel"
mimick relay write -p hwi_v2.relay1 "Power Button" on
mimick connect hwi_v2.tty0

HWI v1​

One board, four peripherals​

Example​

GPIO​

Pin banks​

Limits​

Relay​

Use it​

HWI v2​

Location​

Example​

Pins​

Limits​

Use it​

HWI v1

One board, four peripherals

Example

GPIO

Pin banks

Limits

Relay

Use it

HWI v2

Location

Example

Pins

Limits

Use it