ovos-virtual-mark1
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, thex=/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, andmouth.faketalkresting on frame 0. - Every received line is echoed back as
Command: ...,versionis answered withMycroft 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 sendsvolume.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:
speakan utterance through TTS, the weather layout with a sky condition, date, time, andmycroft.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 announcesmycroft.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=lfed 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.