Skip to main content

ovos-virtual-mark1

Status: Active Unit Tests

A virtual Mycroft Mark 1 faceplate for OpenVoiceOS. It is a software Arduino that speaks the Mark 1's serial protocol, plus a browser GUI that draws the 32x8 LED mouth and the two 12-pixel NeoPixel eye rings with the same pixel layout as the hardware.

The unmodified ovos-PHAL-plugin-mk1 drives it. No OVOS code changes are needed: the plugin opens its serial port with pyserial's serial_for_url, which accepts a socket:// URL, so it connects to this program instead of /dev/ttyAMA0.

OVOS bus  ──▶  ovos-PHAL-plugin-mk1  ──serial over TCP──▶  ovos-virtual-mark1  ──websocket──▶  browser
            (enclosure.* messages)      (mouth.text=..., eyes.blink=l, ...)     (virtual Arduino)

Fidelity

The mouth and eye behaviour is a port of the Mark 1 Arduino firmware, not an approximation:

  • Fonts (5x4 and 8x4) and every mouth bitmap (listen, talk, think, visemes) are generated from the firmware headers by scripts/port_firmware_tables.py.
  • Text scrolling, centring, the two-part $ image protocol, the x=/y=/cP= icon prefixes, the weather layout, and the eye state machine (blink, narrow, widen, look, unlook, spin, timed spin, refill, volume, fill) follow the firmware line by line, including its quirks such as the boot spin emptying the ring before a single pixel chases around it, and mouth.faketalk resting on frame 0.
  • Every received line is echoed back as Command: ..., version is answered with Mycroft Mark 1 v1.4.2, and a connect sends the boot banner a quarter second later, the way the Arduino's DTR auto-reset and bootloader pause do on a real unit. The delay also matters because pyserial's socket transport discards anything received while the port is being opened.
  • The GUI's top button sends mycroft.stop; the knob sends volume.up / volume.down.

Not emulated yet: the long-press hardware menu and the hardware self test. The on-board LED (system.blink) is tracked non-blocking and shown as a status pill; on real hardware it is inside the case.

Quick start

Requires Python 3.10+ and a running OVOS install.

pip install ovos-virtual-mark1          # or: uv tool install ovos-virtual-mark1
ovos-virtual-mark1                      # serial on 127.0.0.1:5555, GUI on http://127.0.0.1:8765

Install the Mark 1 PHAL plugin into the same environment as OVOS and point it at the virtual serial port in ~/.config/mycroft/mycroft.conf:

{
  "PHAL": {
    "ovos-PHAL-plugin-mk1": {
      "enabled": true,
      "port": "socket://127.0.0.1:5555"
    },
    "ovos-phal-mk1": {
      "enabled": true,
      "port": "socket://127.0.0.1:5555"
    }
  }
}

Both keys are needed with plugin 0.2.0a2 and earlier: the plugin's validator reads ovos-PHAL-plugin-mk1, but PHAL hands the constructor the config stored under the entry-point name ovos-phal-mk1. With only the first key the port silently falls back to /dev/ttyAMA0.

Restart PHAL, open the GUI, and talk to OVOS. Listening shows the wave, speech shows the talk shape, and any skill that uses the enclosure API draws on the mouth. To exercise it without a skill:

pip install ovos-mark1-utils
python -c "from ovos_mark1.faceplate.animations import ParticleBox; ParticleBox().run()"

Lip sync

enclosure.mouth.viseme_list is only emitted when the TTS plugin returns visemes. Most modern plugins do not, so the mouth rests on the talk shape during speech. Pair the faceplate with a fake viseme generator if you want it to move.

Control panel

Below the faceplate the page has a control panel. Every control publishes a message on the OVOS messagebus, so the real PHAL plugin reacts exactly as it would to a skill:

  • Eyes: colour, level (brightness), blink, narrow, look with a side, spin, timed spin, on, off, reset, fill percentage, volume, and setting a single pixel to the picked colour.
  • Mouth: scrolling text, the seven viseme shapes, a stock icon from ovos-mark1-utils, and the talk, listen, think, and reset animations. The firmware ignores a viseme while text or an icon is showing, so the viseme buttons reset the mouth first in that case.
  • Demos: speak an utterance through TTS, the weather layout with a sky condition, date, time, and mycroft.stop. "Weather (direct)" sends the same display straight to the virtual Arduino with the classic 8x8 icon, because the plugin's own weather path sends an icon too large for the firmware (ovos-PHAL-plugin-mk1 issue #55).
  • System and lifecycle: the messages core and the listener emit around the enclosure rather than at it. Sleep (recognizer_loop:sleep) really puts the listener to sleep, so speech is not transcribed until Wake; the plugin dims the eyes in steps and looks down. Wake (recognizer_loop:wake_up) wakes the listener, which announces mycroft.awoken, and the plugin resets, blinks and restores the level. No internet shows the warning icon, Enclosure reset restores eyes and mouth, Mute and Unmute drive the board LED, and Blink LED flashes it a chosen number of times.

The panel is a producer in the terms of ovos-ui-enclosure-protocol: it publishes the enclosure.* messages with the data keys that contract lists, and the lifecycle messages under their canonical ovos.* topics from ovos-spec-tools (ovos.listener.sleep, ovos.utterance.speak, ovos.stop), which the bus bridges to the legacy recognizer_loop:* and mycroft.* names for older consumers. The listener side of that protocol is the PHAL plugin, not this emulator: the virtual Arduino sits below it and speaks the firmware's serial protocol.

Two plugin behaviours to know about. The date and time displays switch mouth animations off while they are up (ten and five seconds) and the plugin blocks for that long, so talk, listen and think are ignored meanwhile; the "Re-enable animations" button publishes enclosure.mouth.events.activate if they get stuck, and "Disable animations" publishes the deactivate counterpart. And enclosure.mouth.smile does nothing on any Mark 1: firmware 1.4.2 has no smile handler, its bitmap is commented out.

  • Raw serial: a line such as eyes.look=l fed straight to the virtual Arduino, bypassing the bus. Useful when OVOS is not running.

The bus link defaults to ws://127.0.0.1:8181/core; change it with --bus or disable it with --no-bus. The status row shows whether the bus and the PHAL serial link are up.

Restart order

The PHAL plugin does not reconnect if the emulator restarts: its serial reader logs read failed: socket disconnected in a loop until PHAL itself is restarted. Start the emulator first, then PHAL. The same reader behaviour, a retry loop with no backoff or port reopen, is what a real Mark 1 shows when its UART hiccups.

Options

ovos-virtual-mark1 [--host 127.0.0.1] [--serial-port 5555] [--http-port 8765]
                   [--bus ws://127.0.0.1:8181/core | --no-bus] [-v]

GET /state returns the current faceplate as JSON. The websocket at /ws streams it on every change and accepts {"type": "button"}, {"type": "knob", "direction": "up"|"down"}, {"type": "serial", "line": "..."} and {"type": "bus", "msg_type": "...", "data": {...}}.

Geometry notes

Firmware pixels 0 to 11 are the ring the firmware calls RIGHT and 12 to 23 the ring it calls LEFT; the GUI draws them on the viewer's right and left. Ring index 0 sits just left of the top of the ring and indices increase counter-clockwise, which is what makes eyes.narrow close from the top and bottom and eyes.look=l leave three pixels lit on the left. Flip RING_X in static/faceplate.js if your unit disagrees.

Development

uv sync --extra test
uv run pytest
uv run ruff check .
uv run ovos-virtual-mark1 -v

just recipes exist for each of these. To refresh the firmware tables:

git clone https://github.com/MycroftAI/enclosure-mark1
just port-tables ./enclosure-mark1

Credits

The faceplate's vector styling, the silver rim, dark glass, mic grille, ring tracks and LED glow, follows Timon's Mark 1 artwork for the OVOS installer wizard, used with thanks. The firmware tables are derived from Mycroft AI's Apache-2.0 licensed enclosure firmware.

License

Apache-2.0. The fonts and mouth bitmaps are derived from the Apache-2.0 licensed Mycroft AI firmware.

Metadata

Release files for ovos-virtual-mark1 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ovos-virtual-mark1 0.1.0
File Size Uploaded Provenance Actions
ovos_virtual_mark1-0.1.0.tar.gz 43.3 kB Without provenance Details for ovos_virtual_mark1-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ovos-virtual-mark1 0.1.0
File Interpreter ABI Platform Actions
ovos_virtual_mark1-0.1.0-py3-none-any.whl Python 3 none any Details for ovos_virtual_mark1-0.1.0-py3-none-any.whl

Total release size: 81.1 kB

Release files / ovos_virtual_mark1-0.1.0.tar.gz

Download URL ovos_virtual_mark1-0.1.0.tar.gz
Size 43.3 kB
Tags Source
SHA-256 checksum
How to use checksums
91f5a20c8166b6e152914dc093b31f8c96208d3da060ee0aa98c80abf8e94dc1
BLAKE2b-256 checksum
How to use checksums
616fc0361ff3495ed148f25cbe5a32c09fe527e30dffd84d843120a05f49ca39
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / ovos_virtual_mark1-0.1.0-py3-none-any.whl

Download URL ovos_virtual_mark1-0.1.0-py3-none-any.whl
Size 37.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
42cd0ce5389016e88c60c6ad53df8277cfec398c96d13bf50f33bf5f0362c288
BLAKE2b-256 checksum
How to use checksums
e43de20107921d15eca76a5213f373da5139a984e17f8c9e099df7a27f52c03a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for ovos-virtual-mark1 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page