# Recovery and Factory Reset

What to do when the device is in a state you cannot reach from the editor.

## Deciding how far to go

Work down this list. Each step is more disruptive than the one above it.

| Symptom | Try |
|---|---|
| PLC stopped, editor connects fine | Press **Play** |
| Program behaving oddly after a change | **Clean Upload** |
| Editor cannot find the device | Connect screen, keyboard, and mouse and check network settings on the graphical interface |
| Editor finds it but cannot connect | Check credentials, then restart the device |
| Runtime unresponsive | Restart the device |
| Lost the runtime password | Reset the runtime users |
| Lost the Linux password | Local console recovery, then reimage |
| Filesystem corrupted | Reimage |

## Lost runtime credentials

The account you created on first connection lives on the device, not in any
cloud service, and there is no reset link.

If you still have terminal access, the account database can be cleared on the
device. With no accounts present, the next connection from the editor offers
**Create First User** again.

```bash
# Stop the runtime
sudo docker stop openplc-bootloader
sudo docker stop openplc-runtime

# Remove the account database
sudo rm /var/lib/openplc-runtime/restapi.db

# Start the runtime again
sudo docker start openplc-bootloader
```

The runtime recreates an empty database on start. Allow about twenty seconds,
then connect from the editor and create a new account.

```{admonition} This clears runtime accounts only
:class: caution

Other data in the same directory is not affected, including retained
variables, installed licences, and `project_snapshot/`, which holds a copy of
the original project files stored with every upload and recoverable from the
editor.

Take a copy of `restapi.db` first if you may need to restore it. It can only be
restored alongside the `.env` file that was in place when it was written, since
the stored password hashes depend on the secrets that file holds.
```

Removing `/var/lib/openplc-runtime/.env` has the same effect. The runtime
regenerates the file with new secrets on start, and deletes the account
database as part of that, because the existing password hashes cannot be
verified against new secrets. Removing `restapi.db` alone is the narrower
operation and is preferred.

If you do not have terminal access, reimage.

## Lost Linux credentials

If you have physical access, connect a monitor and keyboard. A local console
session is often enough to recover, and standard Raspberry Pi single-user boot
recovery applies.

If you do not have physical access, reimage.

## Reimaging

This is the full reset. It restores the operating system, the OpenPLC runtime,
the SPI configuration and the Synergy libraries to their factory state.

**It erases everything on the device**: your PLC program, runtime user accounts,
network configuration, any Python or C++ code you have written, logs, and
anything else stored locally.

### Before you start

- Copy off anything you need, using `scp` or `rsync` from your workstation.
  See {doc}`../advanced/accessing-the-device`.
- Confirm you have your project files on your workstation. Every upload also
  stores a snapshot of the original project files on the device, which the
  editor can recover, but reimaging erases it.
- Note the network configuration you will need to restore.

### The procedure

1. Download the SLM-RP4 image from
   [here](https://facts-eng.com/releases/slm-rp4-latest.img.xz).
2. Download and install Raspberry Pi Imager from
   [raspberrypi.com/software](https://www.raspberrypi.com/software/).
3. Shut the SLM-RP4 down (see {ref}`clean-shutdown`) and disconnect 24 VDC.
4. Remove the SD card from the SLM-RP4 (see {ref}`raspberry-pi-status-leds`)
   and insert it into a card reader on your computer.
5. Open Raspberry Pi Imager. Under **Choose Device**, select **Raspberry Pi 4**.
6. Under **Choose OS**, select **Use Custom** and choose the SLM-RP4 image you
   downloaded.
7. Under **Choose Storage**, select the SD card. Writing erases the selected
   drive; confirm it is the SD card.
8. Click **Next**. When asked whether to apply OS customisation settings, choose
   **No**. The image already contains the SLM-RP4 configuration.
9. Confirm the write and wait for Imager to finish writing and verifying.
10. Eject the SD card, insert it into the SLM-RP4, and continue with
    {ref}`after-reimaging`.

(after-reimaging)=
### After reimaging

1. Wire and power the device; wait for it to boot.
2. Confirm it appears in the editor's **Search**.
3. Connect and create the first user again.
4. Re-apply your network configuration.
5. Build & Upload your project.
6. **Change the default password**. See
   {doc}`../advanced/accessing-the-device`.

## Backing up

Preparation makes reimaging considerably faster.

**Your PLC project** lives on your workstation, in the editor. Put it in version
control. The
[source control features](https://edge.autonomylogic.com/docs/openplc-editor/workspace-overview/source-control)
in the editor are the easiest route.

**Your Python or C++ code** should be in a repository, not only on the device.

**Configuration to record:**

- The device's IP address and how it is assigned
- The runtime username. Keep the password in a password manager.
- The backplane arrangement, slot by slot
- Any HAL settings changed from the defaults
- Which protocol servers are enabled, and on which ports

Most of that is already in your project file, which is one more reason to keep
the project in version control.

## Getting help

If a device is unrecoverable, or the hardware appears faulty rather than
misconfigured, contact [Synergy Logic](https://www.synergy-logic.com).

Have ready the information listed in {ref}`troubleshooting-get-help`.