SHOW DEVICE SCREEN
Position and toggle the elements of each device screen (clock, labels, widgets) with a live preview.
๐ผ๏ธ Open Layout Editor
PANEL OPTIONS
Rotate the whole screen upside-down (for inverted mounting). Applies instantly.
Fixes a touch layer mounted differently than the panel โ taps landing mirrored or on the wrong axis. Independent of the display flip above, so rotating the image no longer rotates the touch. Change one at a time and tap to check; all three off = panel default.
Fixes panels that show inverted colours (e.g. yellow appears blue). Applies instantly โ flip this if the colours look wrong.
Fixes panels wired in the opposite channel order โ red shows as blue, blue as orange, while green stays correct. Independent of Invert colours above, which affects all three channels. Applies instantly. No effect on the AMOLED and mono panels.
Show LVGL's on-screen FPS + CPU% counter (bottom-right). Applies instantly.
VISIBLE SCREENS
Hidden screens are skipped when cycling screens on the device.
When a source starts playing, the device jumps to its screen (radio, SD player or Bluetooth). Hidden screens are never shown, and screens outside the cycle (settings, pickers) are never interrupted.
BOOT & SPLASH
Custom logo from the SD card (LVGL RGB565
.bin, any size โ auto-fit to the panel). Requires an SD card; empty = built-in logo.
File:
(built-in)
Changes apply instantly on the device display.
Idle time before the screensaver starts. 0 = OFF.
Keeps the screen on while radio, SD or Bluetooth audio is active.
This screensaver shows the widgets defined in the MQTT settings.
Configure the broker connection and widgets on the
๐จ MQTT tab.
After the idle delay the current screen stays on but the backlight
drops to this level. Any tap or encoder restores full brightness.
๐ก For clock-based dimming (dim at 22:00, brighten at 07:00), make a
pair of time rules on the rules page.
Plays LVGL
.bin slides from the SD card. Convert images with
scripts/img2lvgl.py and upload them via the SD file manager.
Enter the folder as a full path starting with /sdcard,
e.g. /sdcard/slides/320x240 (letter case doesn't matter).
Polls a JSON endpoint and renders one value. Active when screensaver style is "Dashboard".
Must return JSON. HTTPS supported via cert bundle.
Dot/bracket path into the response, e.g.
rates[0].mid,
main.temp, data[2].value. Empty = use root.
Appended to the value. Leave empty for none.
Minimum 5 s. Default 60 s.
Plays a melody when the value crosses a threshold. Fires once per crossing;
rearms when the value comes back across.
When off, the 10-band EQ is bypassed entirely. Volume is unaffected.
Mono sums left and right into both channels โ for single-speaker builds.
This affects the output only, not the stream itself: the CHANNELS readout on the device
and in the web player keeps showing the source format (so a stereo stream still reads
STEREO), and the VU meters keep their stereo image.
Bluetooth playback is unaffected (it bypasses the DSP).
How the 0โ100 % number maps to actual output gain.
Tapered (default) raises the position to the fourth power, so the quiet end of the
scale is fine-grained and usable. Gentle squares it instead โ half as steep in dB,
for amplifiers that already taper in hardware. Both reach full output at 100 %.
Gentle is louder at low settings: 20 % is โ28 dB against โ56 dB tapered,
so turn the volume down before switching. Applies instantly.
Bluetooth is unaffected (the module scales in hardware, outside the DSP).
Percent, 100 for no limit. Every slider stays
0–100 — on the screen, here, in the app and in a rule.
What changes is how much of the amplifier full deflection asks for: at
50, a volume of 100 is half power, and the whole travel spreads over the
half the speakers can take. For a box that distorts or bottoms out near
the top, this is the setting, not a smaller number on the slider.
Applies instantly, and to the fade-in of a wake-up
rule and the level of a spoken notification as well. Bluetooth is not
covered: that volume is the module's own, set over its own link.
When on, if the radio was playing before a restart, it resumes the last station automatically after boot.
When on, starting playback on the phone takes over the output โ it stops the radio or the SD player โ and starting the radio pauses the phone. Starting SD playback always pauses the phone, regardless of this setting.
Plays a signal on the left channel, then the right โ a quick way to verify the wiring, amp and speakers without an SD card or stream. Uses the current volume.
IR REMOTE
Any remote will do โ the radio learns the codes rather than shipping a
key list: NEC (including the cheap LED-strip remotes), Samsung, RC5 and
Sony are decoded. Point the remote at the receiver, press a key, and it
appears below; then bind it to an action. Up to 20 keys, changes apply
immediately.
On the playlist and SD browser screens, Next and Previous move the selection, and any of Play, Play / stop or Pause / resume opens what is selected โ so those keys double as navigation and you need no separate ones. Stop still stops.
On the playlist and SD browser screens, Next and Previous move the selection, and any of Play, Play / stop or Pause / resume opens what is selected โ so those keys double as navigation and you need no separate ones. Stop still stops.
REMOTE BUTTON
IR code
โ none โ
HARDWARE REMOTE (ESP-NOW)
Paired remote
โฆ
Last contact
โฆ
The remote talks to the radio over ESP-NOW, not Wi-Fi โ this button only
opens a 60-second window during which the radio accepts a pairing
request. Press it, then start pairing from the remote's own menu.
Pairing again replaces the stored remote.
The remote sleeps between button presses, so โlast contactโ is the age of the last frame it sent โ hours of silence is a healthy remote on battery, not a broken link.
The remote sleeps between button presses, so โlast contactโ is the age of the last frame it sent โ hours of silence is a healthy remote on battery, not a broken link.
Pick a network instead of typing its name. While connected, a scan
briefly hops off-channel and a playing stream may stutter.
Leave blank to keep the existing password.
Web address of the device โ copy & paste into a browser.
Clear the field for an automatic name derived from the MAC.
HTTP folder whose directory listing comes back as JSON. Saved on
this device and used by the Network Music screen and its playlist.
How the clock is shown on the device's home screen. Applies instantly.
How the date is shown on the device's home screen. Applies instantly.
Weekday shown in front of the date on the home screen. Pick a language preset or type your own — the device stores exactly what you enter. An empty box falls back to the English name.
Max 63 chars. Select a preset or type manually.
โ Changing the timezone while events are scheduled may cause an already-fired
event to trigger again (or a due event to be skipped) if the local date shifts.
Set your timezone once during initial setup and avoid changing it later.
When disabled, the device does not connect to the broker.
Leave blank to keep the existing password.
Must be unique per broker โ two devices sharing one ID disconnect each other in a loop. Leave blank for an ID derived from this device's MAC.
Device topics will be: <base>/state/* and <base>/cmd/*. Publishing any action string to <base>/cmd/action runs it, including
macro:N, which fires the rules waiting on that number.
๐ง Edit MQTT Widgets
Up to 6 widgets (toggle / slider / label) shown on the MQTT screen.
Lets a rule send you a message through a bot โ
add a Telegram block to a rule in the
rules editor.
Off means no task, no connection and no cost.
Seconds. 0 turns receiving off; below 5 is
raised to 5. A
/command written in the chat runs the rule
whose trigger is Telegram command named command โ
make one in the rules editor.Cheaper than it reads. The connection is kept open
and Telegram is asked to hold each check for up to 15 s, so checking
every 15 s is one handshake rather than four a minute. The cost of a
check is the handshake, not the question.
Only messages from the chat id below are
obeyed โ a bot's name is public, so without that anyone who finds it
could drive the radio. Anything that is not a command is ignored, and
nothing from Telegram is ever shown on the screen.
Talk to
@BotFather
to create a bot and get its token. Kept in NVS, never sent back to
this page โ leave the field empty to keep the stored one.
One reader per bot. Telegram lets a single
client hold
getUpdates, so a token already being polled by
Node-RED, a script or another device cannot also be read here โ checks
come back 409 and the log says so. Give this device a bot
of its own if something else already has one. Sending is unaffected;
only reading collides.Where a message with no chat of its own goes. Your
own id comes from a bot such as
@userinfobot;
a group id starts with a minus.
Shows current conditions on the device's home screen.
Widget position is set in the layout editor.
Search powered by Open-Meteo, or enter coordinates manually. Saving remains a separate step.
Display only โ the device always fetches the data in ยฐC.
Text shown next to the icon on the device. Pick a language preset or type your own — the device stores exactly what you enter. An empty box falls back to the English name. Keep them short: a long name widens the widget and can run off a narrow screen.
โ
FILE TOOLS
HARDWARE
Remap GPIO pins for display / touch / SD / encoder / Bluetooth, stored on the
device. Advanced โ wrong pins can blank the display (recoverable here).
Opens the built-in setup page.
๐ Open pin setup
GENERAL-PURPOSE I/O
Drive the free GPIOs yourself โ a relay, an LED, a fan โ or read one as an
input (switch, PIR, reed contact) and let it run any action a button can.
Assign the pins under pin setup first.
๐ Open I/O panel
RULES
"When this happens, do that" โ a trigger (a time, a device state, a button
bound to
๐งฉ Open rules editor
macro:N), conditions that have to hold, and a sequence
of actions. Built as blocks on a canvas, with a live trace of what fires.
๐ฉบ Diagnostics
Live device health, refreshed every 2 s while this tab is open โ the same
snapshot as Settings โ System โ Diagnostics on the device.
Copy report puts it on the clipboard as plain text, every
task stack included, ready to paste into a bug report.
Loadingโฆ
Extra log lines on the serial console (115200 baud), per subsystem โ
for hunting a problem on a device that is already flashed, without a
debug build. Off by default; the choice is saved, so an armed flag
also covers the next boot. Leave it off in normal use: the busiest
flags print several lines per second.
Loadingโฆ
FIRMWARE (OTA)
Current version
โฆ
Show an update prompt on the device screen when a newer firmware is
available. The device always checks at boot โ this only controls the
on-screen prompt.
Upload an application image โ
atlascube.bin, or
AtlasCube-<display>-ota.bin for your display from
atlascube.net/flash.
The device writes it to the inactive slot and reboots into the new firmware.
A release's AtlasCube-<display>.bin (without
-ota) is the full-flash image for USB flashing and is
rejected here. Do not power off during the upload.
Download the running firmware as a
โฌ๏ธ Download image
.bin โ the same image the
section above installs. Keep it before updating, then re-upload it there
to roll back. Firmware only: settings, web UI files and WiFi credentials
are not included.
Built
โฆ
Re-upload the web UI after an app-only OTA left it behind (the warning
above). Pick the raw files from
spiffs_image/www/ โ get the
matching set (AtlasCube-www.zip) from the
latest release. Include
www_version.txt in the selection to clear the warning.
HTML/CSS/JS are gzipped on the device; .ico isn't supported here.
Download every user file on the
config partition (settings,
theme, events, MQTT, layout and the station list) plus the hardware
pin map as a single .json โ a snapshot to keep before a
full USB flash, which erases them. Wi-Fi/MQTT passwords live in a separate
secure store and are not included. Same file format as the
built-in setup page โ a backup made there imports here
and the other way round.
Restore a backup made above or on the setup page. Existing files are
overwritten; a restored pin map needs a full power cycle (not just a
restart) to take effect.