Flash your device
Put ZephOS on a blank board over USB-C. A short button sequence, and the companion moves when the bus does.
A board arrives blank. ZephOS goes onto it over the USB-C cable, from the companion you just installed. Give it a few minutes.
Open Devices → Setup. On first launch, the Get your device step runs the same flow in place.
What you do
Plug the board into your Mac
The companion watches the USB bus and lists what it can see. A board already sitting in download mode appears under Detected devices — pick it and you skip ahead. Otherwise take My device isn't listed, which walks you through waking it.
Pick your model
A blank board has no firmware, so it cannot say what it is. You say. The picker offers the boards the companion flashes from blank today — the ESP32-S3-Touch-AMOLED-1.8 and the ESP32-S3-Touch-AMOLED-2.06 — and your choice drives the rest: the button sequence, the board diagram, the image set.
Put it in download mode
A short sequence on the buttons: connect the cable, power the board down, then hold one button while you tap another. The sequence belongs to the board — the 1.8 and the 2.06 want the same one, and the 1.75C wants its own, so read the block with your board's name on it. The companion draws the same steps against a diagram of the board you picked, highlights the button each one wants, and re-reads the USB bus every 700 ms — so it advances when the device actually changes state, not when you tell it you pressed something.
- 1
Plug it into this Mac.
Use the USB-C port on the right edge, between the two buttons.
pressDone when: The Mac sees the device on USB
- 2
Hold the button until the screen goes dark.
About six seconds — keep holding past the first flicker.
holdDone when: The device drops off USB
- 3
Two buttons, in order.
Do it in the order shown below: hold the first, press the second for a moment, then release the first.
holdpressreleaseDone when: The board comes up in download mode
- 1
Plug it into this Mac.
Use the USB-C port on the bottom edge.
pressDone when: The Mac sees the device on USB
- 2
Hold the middle button until the screen goes dark.
There are three buttons on the top edge; this is the middle one, marked PWR. About six seconds — keep holding past the first flicker.
holdDone when: The device drops off USB
- 3
Two buttons, in order.
Hold the left button on the top edge, marked BOOT/-. While holding it, press the middle button (PWR) for a second and let go of it. Then release the left one. The third button is not used.
holdpressreleaseDone when: The board comes up in download mode
The boards differ, so each sequence names the boards it is for. These are the steps the companion’s flash wizard walks you through, in the order it asks for them.
Choose the firmware
The newest published build, downloaded from the update channel. The build bundled with the app, which works with no internet. Or a folder of signed images, if you built your own.
Let it write
Bootloader, app image, second-core image, a verify pass, then a restart. A setup flash also wipes the data partitions first, so the device comes up factory-fresh and unpaired.
When it finishes, the device reboots and the companion takes you straight to connecting it. If it comes back with a dark screen instead, the wizard shows you the buttons to power it on by hand.
The screen stays dark
The display goes dark when the device enters download mode and stays dark until the new firmware boots. The progress you watch is in the companion window.
If it does not enter download mode
The companion waits up to two minutes for a device in download mode to appear, and it writes nothing until it sees one. So a mistimed press costs you the wait and nothing else: cancel, and run the buttons again. While it waits, the status line reports what the bus actually shows — the device still running, or no device attached at all.
Once bytes are going down the cable, let it finish. The device needs the whole image set to boot, so leave the cable in until the wizard says it is done.
The same USB path is how a device with broken firmware gets rescued — see Recover a device.