Troubleshooting

Problems by stage, then how to recover a box, then how to report what is left.

Flashing

• "Your browser cannot flash over USB." Use Chrome or Edge on a computer. Firefox, Safari, phones and tablets have no Web Serial. The page must also be opened over HTTPS, which it is at its normal address.
• The port list is empty, or the board is not in it. In order: the cable (many carry power only; try another); the port (the one not labeled UART or COM, see Boards); install mode (hold BOOT, tap RESET, release BOOT, then press Connect again; on the ATOMS3 Lite hold the side button until the LED is green). On the Freenove the OTG port shows nothing at all until install mode. No driver is needed on Windows 10 or later, macOS or Linux for these boards; on Linux your user may need to be in the dialout group.
• Two ports listed. Pick USB JTAG/serial debug unit. The other is a USB-to-serial chip on the board and can flash but can never do the Wi-Fi step.
• Install stops part way. Usually the cable or a USB hub. Plug the board straight into the computer, start again from install mode. An interrupted install leaves nothing to clean up; the next install overwrites it.
• After "Installation complete" the page offers to install again. The board is still in install mode: a board put there by hand stays there through the page's own reset. Tap RESET once (short press on the ATOMS3 Lite), or unplug and replug, then press Connect again. This is the most common snag by far.
• The board's LED stays lit after flashing on a devkit. Harmless: the factory firmware lit it, and the firmware leaves it alone.

Wi-Fi

• The box will not join. The network must be 2.4 GHz; the ESP32 does not see 5 GHz networks. Check the password, and that the network is not hidden or restricted to known devices.
• No "Connect to Wi-Fi" in the dialog. The page is not hearing the box: wrong port (see above), or the box is still in install mode (tap RESET). Or use the fallback: join the amble-home-xxxxxx network the box makes and set up Wi-Fi from the page that appears (http://192.168.4.1/ if it does not).
• amble-home.local does not open. Some networks and some Windows setups do not resolve .local names. Use the box's full name (amble-home-xxxxxx.local) or its IP address from your router's device list. With two boxes, amble-home.local answers from whichever is quicker; use full names.
• The box is on a separate IoT network. It needs to reach Home Assistant on port 6053, and you need to reach it on port 80 (its pages) and 3232 (over-the-air updates).

The Edit page

• Account sign-in fails at once. The box has no internet: it is on its own setup network, or your network blocks it. The box makes the sign-in call, not your browser.
• "Account not found" or a sign-in error with a code. Wrong region, email or password; try the region the app signs you into. Code 20014 is amaran's "no such account".
• Signed in, but no fixtures, or the wrong ones. The account must be the one your lights are paired to in the amaran app. Lights paired in Sidus Link only need bringing into the amaran app first (Lights).
• The database will not open. Quit the amaran desktop app and try again; make sure you picked amaran.db in the _secure_id folder (Importing). The page cannot read the phone app's data.
• Two rows with the same mesh id. The app re-paired a light. The newer record is kept, the other skipped; nothing to do.
• Forgot the PIN. Erase the box from the flasher page (check Erase device) and set it up again; there is no reset for the PIN alone.

Lights

• A fixture stays a dashed outline (never heard). The box has not heard that light. Check that the light is powered, its Bluetooth is on (Sidus BT in the light's menu) and the amaran app can reach it. Then range: move the box closer, or nearer to any light of the mesh, since fixtures relay for each other. Last, the keys: if every light is dashed, the mesh the box imported is not the mesh the lights are on; re-import after making sure the app shows them.
• Lights worked, then all went unavailable. The box went off the network or rebooted; check its Home page and Wi-Fi signal in Home Assistant. Press Re-sync fixtures after it is back.
• Home Assistant lags behind the app. By design the box asks each light every 15 seconds; a change made in the app shows within that time. Re-sync fixtures asks now.
• Commands are ignored after an erase and re-import. Rare, and explained on Updating: the box came back on a mesh address it had used before. Erase and flash once more.
• Mesh send failures above zero. The radio stack refused to queue a message. Press Restart on the device page; if it keeps climbing, report it with the counters.
• A light does something odd in color mode. Color temperature and color are exclusive on the fixture; the last one sent wins. Set the one you want again.

Home Assistant

• The box is not discovered. Add the ESPHome integration by hand with the box's address. Discovery needs Home Assistant and the box on the same network segment, or mDNS forwarded between them.
• Entity ids changed. You have a new box (a new name) or you erased it and it is a new device. Rename the entities, or re-point scenes and dashboards. Renaming a light in the amaran app does not do this; see Home Assistant.
• One light stays unavailable after an update or a Wi-Fi drop while the others came back. The box has it (its Home page shows the light heard), and Home Assistant missed that light's first state after reconnecting. Reload the box's integration entry: Settings, Devices and services, ESPHome, the box, the three-dot menu, Reload. Changing the light from the amaran app brings it back too. A known bug, on the issues list.
• I can't find a "Visit" link to the box. There is none; bookmark the box's address (Home Assistant).

Recovering a box

Whatever state a box is in, the flasher page with Erase device checked brings it back to a fresh box: set up Wi-Fi and import again. If the page cannot see the board, start from install mode and the cable checks above. A box that will not enter install mode at all, by any button, is a hardware question for the board's maker.

Reporting a problem

Open an issue. Please include:

• The board and the browser and operating system you flashed from.
• The firmware version (the flasher page shows it under the button; Home Assistant shows it on the box's device page as "amble-home 1.0.1" or similar).
• Which step you were on, what you did, what you expected, what happened.
• What the box's Home page showed, and the diagnostic counters from Home Assistant (sent, replies, timeouts, refused, send failures, unknown sources, Mesh up).
• The light's model and family, if the problem is a light.
• If you have ESPHome installed, the output of esphome logs amble-home.yaml --device amble-home-xxxxxx.local around the moment it went wrong. The box's logs say "fixture 3", never a name or an address.

Please leave out: your mesh keys, your amaran.db, fixture hardware addresses, your amaran password, and your Wi-Fi details. Nothing the project asks for needs them, and an issue is public forever. If a problem genuinely needs the layout of your mesh, say so on the issue and the author will arrange a private channel.

amaran and Aputure support have nothing to do with amble-home; please do not send them its problems.