Troubleshooting
If your Candle Controller is not booting up properly you may be able to fix it.
TIP: always start with a reboot of the controller
Candle has self-repair mechanisms which are run whenever the controller starts.
1. What's the problem?
The display is mostly empty and unresponsive
This can happen if your system could not find its WiFi network. If your WiFi is down, fix that and then restart the controller, so it can find it again.
If this doesn't work, or if you changed your WiFi name or password, simply wait until the Candle Controller sets up a WiFi hotspot called Candle XXXX (where the X-es are random letters). Connect to it from a laptop, and then a window should pop up asking which WiFi network the Candle Controller should connect to.
Alternatively, plug in a network cable and restart the controller.
Updating is taking more than two hours
Some update processes can take a long time. However, taking more than two hours is a bit much. You could try to unplug the controller and plug it back in again.
I see a red screen with ERROR on it
The first step is to unplug the controller, wait ten seconds, and power it up again.
If that doesn't work, try plugging the Candle's SD card into your computer.
If a new drive shows up, then you can proceed to the Fixing section of this page. If not, then try running disk repair software to fix the SD card.
The display shows a browser error
Candle's display is essentially a webbrowser that shows the output of a server that is running internally on the device. If that server - the actual Candle Controller software - isn't working, then the browser is trying to open a page that is not being provided, resulting in an error.
Scroll down to the Fixing section of this page, and follow the steps to restore the Candle Controller software.
if you see a single line starting with Error: ENOENT: no such file or directory, that will also be solved by this fix.
I attached a display but don't see anything
Use the HDMI port closest to the power plug. The display is only activated on a Raspberry Pi 4 with at least 2 Gb of memory (although you can override this). If that's what you have, then try a reboot. If that doesn't work your display might be unsupported.
I cannot open links to other websites from the touch screen
That is as intended. Open the Candle Controller interface on your phone, tablet or laptop, it will work there.
The touch input appears on the opposite side of the display
This can sometimes happen if you have rotated the display to 90, 180 or 270 degrees. A reboot should solve this.
I cannot open candle.local on Android
Put http:// before it. You may even need to use the controller's IP address, which you can find under Settings > Network. So, for example: http://192.168.1.34
The web-app on my phone seems to show an older version of the controller
Remove the web-app and recreate it again.
I see a low memory warning on the shutdown page
Try uninstalling addons that you don't need, or upgrade to a Raspberry Pi with more memory. Or you can ignore it.
I restored a backup, but some of my things are translucent
Make sure all the addons you were using before are installed.
I restored a backup, but my Zigbee things are not connecting
Give it a little time. You may have to switch of each device and switch it on again, or simply press a button on them.
2. Fixing the controller
SD card tricks
We've built a number of tools into the Candle Controller that you can enable by placing certain files on the SD card, and then plugging it into your Candle controller again. If your Candle Controller isn't too damaged, then it will read these commands.
Start by shutting down or unplugging the controller and removing the SD card from it. Now plug that SD card into your laptop. A drive called "BOOT" should appear.
The first step is to take a look at the candle_log.txt file on that drive and spot any errors.
If you need more information, place a file called generate_debug.txt on the SD card, place it back in the Candle Controller, and power it up again. After about a minute or two shut down the controller and inspect the SD card on your computer again. You should now find a new file called debug.txt with lots of information about the system, including any errors that were detected.
Start the recovery process
Modern Candle Controllers (2.0.2 and above) have a built-in recovery system which can fully restore the system to the latest available version of Candle. You will need to connect a network cable for this to work, as this process downloads the latest version of Candle from the internet.
You can start this process manually in two ways.
If your controller has a display, and you still see a Candle logo when the system starts, then you can attach a keyboard and press the ALT key on the keyboard once you see a Candle logo. You'll know the key press was recognised if you see noise on the display.
The other option is to replace the contents in cmdline.txt on the SD card with the text in you find in cmdline-update.txt.
Plug the SD card back in and power up the controller again. The update proces should start, and the latest version of Candle will be downloaded from the internet.
Don't worry, this will not affect the personal data on the controller in any way.
Older recovery methods
There are less "intense" options which only replace smaller parts of the Candle software. Candle Controllers comes with an internal backup of the controller software itself. You can ask for this (older version) to be put back by placing a file called restore_controller_backup.txt on the SD card.
Another option is to create a file called restore_boot_backup.txt instead. This will restore a part of the controller that deals with the self-healing features of the controller.
Another option, which will require your controller to have an internet connection, is to download and install the very latest version of the controller software. This is a lengthy process that can take an hour. To do so place a file called force_controller_rebuild.txt on the SD card.
When (if...) the controller detects these command files it will delete them and then start the requested process. The outcome of those processes will be written to the candle.log file.
If you see no indication that the controller is detecting these commands, then the problem is more serious.
3. Options for advanced users
Gaining access to your controller
The short version: check out the readme file on the SD card for instructions on how to gain access and disable read-only mode.
Candle runs on Linux (Raspberry Pi OS), so if you are comfortable with Linux you can do almost anything with your controller.
For security reasons the SSH shell is disabled by default. You can enabled it in a few ways:
- If you enable developer mode, then you can enable SSH from the internet (settings -> developer -> enable SSH). Developer mode can be enabled by clicking on the gear icon on the settings page four times. You can also enable developer mode in the Candle Store addons settings, which will make it more permanent by creating developer.txt for you.
- Place a file called candle_ssh.txt on the SD card. On the next boot SSH will be available.
- Place a file called developer.txt on the SD card. This will enable the SSH shell automatically whenever the system is doing a system update, when it detects an issue and tries to self-repair, or when you disable read-only mode.
- Place a file called emergency.txt on the SD card. This will start SSH and stop other (self-repair) processes.
The default login name is pi and the default password is smarthome. It's recommended to change the password.
If the system is so broken that you cannot gain SSH access, Then you could gain physical shell access by replacing the cmdline.txt file.
In either case you can find more information and options in the readme.txt file on the SD card. For the latest version of the controller you can also find it online.