Core system¶
The device's fixed infrastructure: identity, network, provisioning, firmware, and the inspection tools. These modules are always present and wired by code, so a user does not add or delete them. User-added capability modules, such as Audio or Infrared, live in the Services container instead.
AccessPoint
The device's own WiFi network, at 4.3.2.1: joining it opens the UI by itself, as a sign-in screen. A child of Network, which opens and closes it; http://4.3.2.1 reaches the UI as well. The first known WiFi network's password protects it, so it is open only on a first setup or with an open home network. Its clients receive no stored password or config file.
opens: When it opens: on failure, always, or first setup only.name: The network name:MM-and four MAC digits.clients: The devices on it.
Control
A control desk of switches, encoders, faders and preset pads that puts the device into a named state. Eight switches, encoders and faders sit above 64 preset pads, laid out like a Mackie-style desk (X-Touch, QCon Pro G2), so a physical surface maps onto it.
display: The strip above the desk: what the surface last touched, in words.presets: One pad per preset file. Click applies, right-click names, drag rearranges.name: The name the next save gives its preset.slot: The pad the next save lands on.source: The module the next save writes, by name.save: Saves the source module as the named preset.
Ethernet
The wired interface: which board's wiring it uses, and how it gets an address. A child of Network, which runs the cascade; it holds what Ethernet needs to join it. It exists where Ethernet is compiled in, and as a developer preview on the desktop.
ethBoard: The Ethernet wiring by name.ethType: The PHY chip, seeded per chip and overridden by the catalog.ethPhyAddr: The PHY's address on the management bus.ethRstGpio: The PHY's reset pin.ethMdcGpio: The management clock pin.ethMdioGpio: The management data pin.ethClockGpio: The RMII reference clock pin.ethClockExtIn: Whether the clock comes into the chip rather than out of it.ethSpiMiso: The W5500 data-in pin.ethSpiMosi: The W5500 data-out pin.ethSpiSck: The W5500 SPI clock pin.ethSpiCs: The W5500 chip-select pin.ethSpiIrq: The W5500 interrupt pin.ipSettings: DHCP or Static
FileManager
Browse and manage the device filesystem: a folder tree with an inline text editor. Each folder loads its children on first expand. It is distinct from Filesystem, the persistence engine that writes the config files this panel shows.
show hidden: Reveal dot-prefixed files and folders, such as.config.flash: Flash used and total, as the usage bar.lastSaved: How long ago the configuration was last saved.
Filesystem
The persistence engine: it writes control values to /.config/*.json and restores them on boot, so settings survive a reboot. It is always loaded and runs first, so its load hook fires before any other module sets up. File Manager browses the stored files.
FirmwareUpdate
Over-the-air firmware flashing: what is installed, and how an install goes. A flash swaps the binary and restarts the device, the one change that does not apply live. The flash is driven by the web route; the module shows its progress.
appVersion: The installed version.update: How this device takes a new version: self, host or manual.moonbaseMismatch: The installed version.coprocessorMismatch: The radio chip's firmware, published only while it does not match this app.image: Which image the card describes, drawn as tabs.version: The installed version.needs: The ESP-Hosted release this firmware needs on the radio chip.connect: Start the link to the radio chip, to read and update it over Ethernet.build: The git id, then the build date.firmware: The build variant; on the MoonBase tab, its chip.partition: The installed image against the size of its slot, which a new image must fit.
HttpServer
The embedded HTTP server and WebSocket: it serves the web UI and the REST API behind it. The routes are in The REST API, and the layering in What it is allowed to include.
port: The port the server listens on.
Attribution: Moustachauve
I2cBus
The board's I2C bus: its two pins, opened once and shared by every device on it, with a scan that detects them. A device on the bus, such as the Audio codec, names only its own address; the wires are stated here, once per board. The pins default to unused, so a board without an I2C device claims no GPIO.
sda: The bus data pin; a board's catalog entry sets it.scl: The bus clock pin; a board's catalog entry sets it.scan: Probe the bus now.result: Each address found, named by the module driving it, cut off cleanly past about three.
ImprovProvisioning
Browser-driven WiFi provisioning over serial: the web installer hands the WiFi credentials to a fresh device. A freshly flashed board is off your network. Improv carries that first handoff over the cable the browser already used to flash it.
provision_status: The provisioning state.
Attribution: Improv Wi-Fi
MoonCloud
The container for everything MoonLight does with a server MoonModules runs. It holds no settings of its own. Each thing it does is a child with its own consent: MoonStats reports the install and MoonTalk is a message board. A user who wants one has not agreed to the other.
outbox: The request waiting for the open page to post it.outbox sent: The id of the request the page delivered, which empties the outbox.
MoonStats
One opt-in report about this install, sent once per install or upgrade, so development effort goes where the users are. Off until you answer yes. An upgrade sends one report and a reboot sends nothing.
consent: Whether this install may report.reportedVersion: The version that last reported.version: The version running now.send update: Report again now.
MoonTalk
A public message board between MoonLight devices, off until you turn it on. A child of MoonCloud with its own consent. A message is sent because you typed one: nothing posts on its own.
consent: Whether posting and reading are on.shareName: Whether your device name rides along, a separate decision.message: What to say; typing changes nothing on its own.send: Publish the message and clear the box.
Attribution: Meshtastic
Mqtt
Lets a home-automation hub switch the light on and off and set its brightness and color over MQTT. A small MQTT 3.1.1 client of our own, off until a broker is set, wired by code as a child of Network. Every command goes through the shared control path, so MQTT adds only a transport.
broker: The broker's hostname or IP address.port: The broker's TCP port.username: The broker login, optional.password: The broker password, stored obfuscated like the WiFi one.haDiscovery: Announce a Home Assistant discovery light, opt-in.mqtt_status: Where the connection stands, from disabled and idle through connected, or the error.
Network
Brings the device onto the LAN before the HTTP and WebSocket servers start, trying Ethernet, then WiFi, then its own access point. Network holds the cascade, its mode and the <name>.local address it advertises on whichever interface is up; each interface's settings are on its own card: Ethernet, WiFi and the access point. A desktop builds the same cards over stubs. The order is described under The cascade in the header.
mode: The interface in use.
Pins
A read-only map of which module owns each GPIO, for what role, and whether the pin is safe for it. It is keyed by physical GPIO, the way an OS device manager or a board template is. It walks the live tree for every claimed pin, holds no state, and flags double claims.
pins: A row per claimed GPIO.
System
The device's identity and vitals: its name, how long it has run, and the memory and tick it renders at. The name is the one the network sees, behind mDNS <name>.local, the access point SSID and the DHCP hostname. The readings are described under What it reports in the header.
deviceName: The name behind mDNS, the access point and DHCP.deviceModel: The board model, which selects the installer's catalog entry.firmware: The build variant, kept for the MoonBase recovery image to read.uptime: Time since boot.fps: Frames rendered per second.tickTimeUs: Microseconds one tick takes.heap: Internal heap in use.psram: PSRAM in use.psramType: The PSRAM interface and clock.maxBlock: The largest free internal block, which bounds one allocation.missing scripts: Shipped scripts a module names and the device lacks; an open page downloads them.flash: The flash chip size.flashMode: How the chip reads its flash, and its clock where known, such as QIO, 80 MHz.mac: The hardware address, which tooling identifies the device by.chip: The chip model.cpu: The clock and core count.sdk: The SDK version the firmware is built on.bootReason: Why the device last restarted.mode: How much of the UI is shown, cumulative.factory reset: Delete every setting and preset and restart as freshly installed.logLevel: Serial log verbosity.
Tasks
A read-only diagnostic showing what runs where: the tasks, and the modules inside each. You cannot optimize which module runs on which core until you can see it. Each task has its modules nested beneath it. The list is empty on the desktop.
tasks: A row per FreeRTOS task.core0: What executes on the first core.core1: What executes on the second core, empty on a single-core chip.
WiFi
The WiFi station: the networks the device knows, in the order it prefers them, and the radio's settings. A child of Network, which runs the cascade; it holds what joining WiFi needs. Joining is connect-first, as on a phone: tap a network in range, type its password, Connect.
address: Where to reach the device on its new network, by address.localName: The same, by the.localname.scan: Look for the networks in range.scanned: How long ago the last scan finished.available: The networks in range; Connect joins one now.known: The networks it joins, in priority order.rssi: The signal strength of the joined network.txPower: The power the radio transmits at now.txPowerSetting: Caps the radio's transmit power, for a board that browns out.
AccessPoint, details¶
Getting back in¶
Switch the device on and off four times, each within a few seconds, and it opens for that boot without a password, whatever its setting says. That boot runs in safe mode: the way back to a device whose router changed, with every setting kept.
After a join from the access point¶
A join asked for from a phone keeps the access point up beside the new network for two minutes, and the WiFi card shows the device's links.
Joining moves the radio to the router's channel, which knocks the phone off, so open a link in the browser: the sign-in screen has no address bar.
Control, details¶
The surface¶
Each switch, encoder and fader drives any control you assign; right-click an encoder to see its binding. The first switch drives the master on/off and the first fader the global brightness.
From the second slot on, an unassigned slot follows the effect enabled last.
Presets¶
Click a pad to apply its preset, drag to rearrange. A pad is tinted by its role: layout blue, effects violet, driver green, service amber. Presets has the rest.
Home Assistant¶
Only effects presets reach Home Assistant, so a hub never rewires pins or geometry. Home automation has the setup.
Ethernet, details¶
Choosing a static address¶
Gateway and DNS are optional. A static setting that cannot work, such as a gateway outside the subnet, is not used: the interface keeps DHCP and the card says why.
Changing the addressing of the interface the page reaches the device through asks first, naming where the device will be.
FileManager, details¶
Working with files¶
Click a folder to select it and open or close it, and click a selected file to open the editor. The toolbar acts on the selection: new folder, new file, delete (press twice) and refresh.
Drag files from the desktop onto a folder to upload them.
The editor¶
The editor pretty-prints JSON on open and saves atomically. A binary file loads read-only: download it instead.
Backup and restore¶
Backup downloads the device's files as one .json bundle, and Restore uploads one back. Keep the bundle private: it contains the WiFi password. Back up and restore a device walks through both.
FirmwareUpdate, details¶
The images¶
Each image has its own tab: the app, MoonBase where present, the WiFi coproc on a P4 with WiFi. A Restart in MoonBase button sits on the card.
When MoonBase's version differs from the app's, the card warns and the top bar shows ⬆ MoonBase; installing the matching one from its tab clears it.
The WiFi coproc¶
A P4 with WiFi has its radio on an ESP32-C6, on the WiFi coproc tab: link not started on Ethernet (connect starts it), link down, then its version.
Its major.minor must match the tab's ESP-Hosted release, or the card warns. Install from the release or a file; the device restarts.
I2cBus, details¶
Reading the scan¶
The scan names each answering address by the module driving it, as 0x18 Audio (ES8311). A claimed address that stays silent reads no answer: check the wiring and the device's power.
ImprovProvisioning, details¶
Provisioning¶
Improv Wi-Fi is an open standard, and its sdk-cpp and sdk-js are the specification this implements. Any Improv-capable installer can provision a MoonLight device.
Without a serial link, the device's own access point serves the network instead.
MoonStats, details¶
What it sends¶
The report carries the chip, flash, PSRAM, SDK, device model, memory, light count, and which modules you added. It carries no device name, no addresses, no credentials and no text you typed.
The privacy policy states what is promised.
MoonTalk, details¶
Public and permanent¶
Everything sent is public and permanent: no private message, no recipient, no delete. There is no authentication, so a sender id can be fabricated by hand.
Mqtt, details¶
Which route¶
Home Assistant finds the device over the WLED integration with no broker. Use MQTT for Homebridge, a broker-only network or another hub. Home automation lists the topics.
Getting it connected¶
The status line says why. Give the broker computer's LAN address, never 127.0.0.1, and let port 1883 through its firewall.
Network, details¶
A direct cable to a computer¶
With no DHCP server on an Ethernet-only build, the device takes a 169.254.x.y address after about 15 seconds. A computer on the same network does too, so open <name>.local and set a static address on the Ethernet card.
A DHCP server that appears later still wins.
Pins, details¶
Reading the map¶
A row shows the GPIO, its owner and role, and the live direction, level and drive.
A row takes a colored edge when unsafe: red for a reserved or double-claimed pin, yellow for a driven role on a strap.
The GPIO usage reference lists the pins per chip.
System, details¶
Safe mode¶
Two failed boots in a row start the next boot with the LEDs off, no MoonLive script and at most 1,024 lights. A failed boot is a crash, a brownout, or a power loss within a minute of starting. Every boot raises the lights over five seconds.
Tasks, details¶
Reading a task row¶
A row shows the task's name, state, core, priority and the minimum free stack seen, and expands to its modules.
A cpu percentage appears only in a profiling build, since the run-time counter costs about 5% of the tick.
WiFi, details¶
The order of joining¶
The device tries the known networks in priority order, ten seconds each to join, and opens its access point after the last. Networks a scan in the last five minutes did not see go to the end of that order. Each network keeps its own IP settings.
Connecting¶
Connect joins a network at once. A network picked from those in range is saved only once it joined, and "incorrect password" says why when it did not.