Deploying to Pi — Deploy, Versioning & Drafts

Overview

The Deploy step is the final — and most consequential — stage of the Configurator workflow. When you deploy, LoopString translates your visual rooms-and-parts diagram into a working Node-RED control program and sends it to your Raspberry Pi. Once deployed, your Pi runs the new program immediately: sensors start reporting, actuators respond to commands, and any control loops begin executing.

Because a bad deploy stops the Pi's control system, LoopString includes several safety layers before and during deployment:

• A pre-deploy validator that catches common wiring mistakes before any file is sent
• A step-by-step progress panel that shows exactly what the Pi is doing
• A FlowSyncBadge that monitors whether the running program on the Pi matches what you last deployed
• Automatic flow snapshots taken on every successful deploy so you can roll back instantly

This document explains all of these features in detail.

Pre-Deploy Validation

Before the Deploy button becomes active, LoopString runs a validator against your draft. The validator checks five categories of problems and assigns each a severity level.

Errors block deployment. You must resolve all errors before the Deploy button will trigger a deploy. Errors catch configurations that would either crash Node-RED or produce a dangerously incorrect control program.

Warnings do not block deployment but indicate a configuration that may not behave as intended. You can proceed with warnings present, but you should understand what they mean.

Info notices are purely informational. They never block deployment.

Validation rule: Missing part definition

This error fires when your draft references a part that no longer exists in the parts library — for example, if the part was removed in a library update after you added it to your draft.

Resolution: Remove the highlighted part from your draft and replace it with a current equivalent from the parts library.

Validation rule: Orphan controller

This error fires when a PID controller or hysteresis controller has no sensor wired to its input, no actuator wired to its output, or both. A controller with no sensor input has nothing to control. A controller with no actuator output has no way to act.

Resolution: Open the Flow Editor, find the highlighted controller, and wire it to a sensor output and an actuator input. See the Flow Editor documentation for wiring instructions.

Validation rule: Sensor wired directly to actuator

This warning fires when a sensor is connected directly to an actuator with no controller in between. While this will deploy successfully, it means the actuator simply mirrors the sensor reading with no control logic — rarely the intended behavior.

Resolution: Add a PID or hysteresis controller between the sensor and actuator.

Validation rule: Signal type mismatch

This error fires when the output signal type of one part is incompatible with the input signal type of the part it is wired to, and no automatic conversion is available. For example, wiring an on/off digital sensor output to a PID controller that expects a continuous numeric temperature value.

Resolution: Check that the wired parts are compatible. You may need to remove the connection and wire through an appropriate intermediate part.

Validation rule: Unconnected part

This warning (or info notice for standalone sensors) fires when a part in your draft has zero wiring connections. Standalone sensors will still publish data to the dashboard and are flagged as info only. Non-sensor parts with no connections — such as an actuator or controller that is not wired — are flagged as a warning.

Resolution: Either wire the part into your control circuit or remove it from the draft.

Where to see validation results

Validation results appear in the pre-deploy panel below the Flow Editor. Each issue lists the affected part by name, explains the problem, and offers a suggested fix. You can click "Remove" on a warning or info issue to dismiss it if you have intentionally designed the configuration that way. Errors cannot be dismissed — they must be resolved in the diagram.

The FlowSyncBadge in the Configurator toolbar also reflects validation state: a red badge with an error icon indicates the current draft has blocking errors.

The Deploy Button

The Deploy button appears in two places:

• In Step 6 of the Configurator guided setup wizard
• In the Flow Editor toolbar at the top of the screen

The button is disabled when any of the following conditions are true:

• The draft has one or more validation errors (see Pre-Deploy Validation above)
• The target device is offline
• No draft is currently loaded
• A deploy is already in progress

When enabled and clicked, the button transitions to a spinning "Deploying..." state and the deployment progress panel opens automatically.

How Deployment Works

Deployment follows a sequence of steps. Each step is shown individually in the progress panel with a live status indicator as the Pi works through them.

Step 1 — Waiting for device

LoopString writes the new flow program to Firebase Realtime Database at a dedicated deploy command path. The Pi polls this path and picks up the command. This step completes as soon as the Pi acknowledges the command. If the Pi does not respond within two minutes, this step times out and the deploy fails.

Step 2 — Installing packages (deploy only, may be skipped)

If your flow uses parts that require Node.js packages not already installed on the Pi — for example, a specialized protocol library — the Pi installs them now via npm. This step is skipped if all required packages are already present. Package installation can take 30–90 seconds depending on your Pi's internet connection.

Step 3 — Saving backup

Before overwriting the running program, the Pi saves a snapshot of the current flows to Firestore. This ensures a rollback target always exists before any change is made.

Step 4 — Deploying flows to Node-RED

The Pi sends the new flow JSON to Node-RED's local admin API. Node-RED loads the new program and immediately begins running it. Because this action restarts the Node-RED runtime, the Pi's agent subflow that is reporting status will briefly go silent. LoopString handles this automatically: if no further status arrives within 30 seconds of this step, the deploy is assumed successful (the expected behavior).

Step 5 — Restarting Node-RED

Some deploy paths include an explicit Node-RED restart after flow injection. This step may not appear or may complete very quickly depending on your Pi's firmware version.

Step 6 — Verifying device health

LoopString checks that the Pi has come back online and the new flow is running. If this step fails, a notice advises you to check the dashboard in a moment — the Pi may still be restarting and will appear online shortly.

If any step fails, the progress panel shows the error message from the Pi, remaining steps are marked as skipped, and a Retry deployment button appears. You can retry without modifying your draft.

The full deploy sequence typically completes in 5–15 seconds when no package installation is needed.

The FlowSyncBadge

The FlowSyncBadge appears in the Configurator toolbar and gives you a continuous view of whether the program currently running on your Pi matches what LoopString last deployed.

Flow synced (green) — The Pi's running program matches the last successful deploy. Everything is in the expected state.

Flow drifted (yellow, clickable) — The Pi's running program has diverged from the last deploy. This happens when someone edits flows directly in Node-RED's local editor on the Pi, or when a manual file change is made on the Pi outside of LoopString. Clicking the drifted badge opens a conflict resolution prompt. Redeploying from the Configurator will overwrite the Pi-side changes.

Sync unknown (grey) — LoopString cannot yet determine the sync state. This appears when the device is offline, when the device has never been deployed to, or briefly after a deploy while the Pi is restarting.

The badge works by comparing a hash of the flow JSON that was deployed (stored by LoopString) with a hash that the Pi computes and reports from its currently running flows. A mismatch between these two hashes sets the badge to drifted.

Flow Versioning

Every successful deploy automatically stores a flow snapshot in Firestore. Snapshots capture the complete Node-RED flow JSON at the moment of deploy. LoopString retains the 20 most recent snapshots and automatically removes older ones.

You can access flow version history from the Configurator History view. For each snapshot you can see:

• The timestamp of the deploy
• Whether the deploy succeeded
• The number of nodes in the flow at that point
• Whether it was a regular deploy or a rollback

Comparing versions

Selecting two snapshots from the history list and clicking Compare shows a diff of the two flow JSONs. The diff highlights which nodes were added, removed, or modified between the two deploys. This is useful for understanding what changed after an unexpected behavior appears.

Rolling back

To restore your Pi to an earlier working configuration, select the target snapshot from the history list and click Rollback. Rollback follows the same step sequence as a regular deploy: the snapshot's flow JSON is retrieved from Firestore, written to the RTDB deploy command path, and the Pi picks it up and installs it. A new snapshot is saved at the end of a successful rollback, so rollbacks are themselves versioned.

Rollback does not modify your current Configurator draft. After a rollback, your draft and the deployed flow are different — the FlowSyncBadge will reflect this. To bring your draft into sync with the rolled-back flow, you would need to manually update your draft to match.

Draft Management

A draft is your work-in-progress Configurator configuration — the rooms, parts, and wiring you have set up. A draft is not the same as a deployed flow. You can have many different draft states saved, and deploying a draft sends it to the Pi, but does not delete or lock the draft.

Auto-save

The Configurator automatically saves your draft to Firestore whenever you make changes. Auto-save runs after every edit: adding or removing a part, modifying a connection, changing a room name, updating a part's configuration. You do not need to manually save your work to avoid losing it.

The drafts picker

Clickin the Drafts button in the Configurator toolbar opens the drafts picker modal. The picker lists all your saved drafts, sorted by most recently updated. Each entry shows the draft name, the build category (for example, "Mushroom cultivation" or "Aquaponics"), and the time of the last update.

From the drafts picker you can:

• Load a draft — switches the Configurator to that draft immediately
• Delete a draft — permanently removes the draft from your account

Creating a new draft

Starting the Configurator setup wizard from the beginning creates a new draft. You can run the wizard multiple times to accumulate several distinct drafts for different rooms, experiments, or Pi devices.

Difference between a draft and a deployed flow

Your draft is the blueprint. The deployed flow is what is actually running on the Pi. They can diverge in two ways:

• You edit the draft after deploying — the draft is now ahead of what the Pi is running
• The Pi's flow drifts due to manual changes on the Pi — the Pi is running something different from what was last deployed from this draft

The FlowSyncBadge tracks the second kind of divergence. The first kind is visible by comparing your draft's current state to the deployment history.

Use Cases

First deploy of a new system

You have completed the Configurator setup wizard for a new grow room: added temperature and humidity sensors, a PID controller, and a heater actuator. The pre-deploy validator shows no errors. You click Deploy.

The progress panel shows the Pi picking up the command, installing the DHT22 sensor library (this is a first deploy so the package is not yet present), saving a backup of the empty flow, injecting the new flows, and verifying health. The whole process takes about 45 seconds because of the package install. After the healthcheck step turns green, your dashboard immediately shows live temperature and humidity readings and the heater responds to the PID setpoint.

Rolling back after a broken deploy

You modified your draft to add a CO2 sensor and wired it to a second PID controller that drives a ventilation fan. After deploying, the fan begins running continuously at full speed instead of cycling based on CO2 levels. You suspect the new PID wiring is incorrect.

Rather than debugging live, you open the Configurator History, find the snapshot from the previous successful deploy, and click Rollback. The progress panel walks through the rollback steps. Within 10 seconds the previous flow is running and the fan returns to normal behavior. You then return to your draft, correct the PID wiring, re-validate, and re-deploy.

Troubleshooting

Deploy times out on "Waiting for device"

The Pi did not acknowledge the deploy command within two minutes. Common causes:

• The Pi is offline. Check the Device Health panel to confirm the Pi is reachable. If it is offline, bring it back online and retry.
• The Pi agent is running but the Tailscale tunnel is down. Check the Tailscale status indicator in the dashboard header.
• The Pi's Firebase connection is disrupted. SSH into the Pi and check whether the Node-RED process is running: sudo systemctl status nodered.

The deploy command remains queued in Firebase RTDB. If the Pi comes back online within a few hours, it will pick up the pending command automatically.

Deploy fails on "Deploying flows to Node-RED"

This step posts the flow JSON to Node-RED's local admin API on the Pi. Failures here are usually caused by:

• A flow JSON that is too large for Node-RED to accept in a single request. This is rare but can happen with very complex drafts containing dozens of rooms and parts. Try reducing the number of parts or splitting the configuration across two Pi devices.
• Node-RED is in an error state from a previous deploy. SSH into the Pi and restart Node-RED manually: sudo systemctl restart nodered. Then retry the deploy.
• A corrupted part template. Check the deploy error message — it may name the specific Node-RED node that rejected the flow. Contact support with the error text if you cannot identify the source.

Validation errors are blocking deploy but the wiring looks correct

The most common case is a signal type mismatch that appears to be a correct wiring. This can happen when a part's output type changed in a library update after you originally wired the draft. The validator checks the current part definitions, which may differ from what you saw when you built the draft.

Steps to resolve:

1. Open the Flow Editor and remove the flagged connection.
2. Check the part's output signal type in the parts library detail view.
3. Re-wire the connection. If the types are genuinely incompatible, you may need an adapter part in between.
4. If removing and re-wiring does not clear the error, try removing the part entirely and re-adding it from the parts library to reset its configuration to the current defaults.

Another common case is an orphan controller error where you can see the wiring visually but the validator reports it missing. Verify that the connection arrow in the Flow Editor is fully snapped at both ends — a loose endpoint that appears connected visually but is not fully attached will not register as a connection in the validator.

Drift detected immediately after a successful deploy

The FlowSyncBadge shows "Flow drifted" shortly after a deploy that appeared to succeed. This can happen when:

• The Pi's Node-RED process applies an automatic change to the flow on startup (rare, usually a missing node substitution). Redeploy from the Configurator to restore the expected state.
• The Pi's system clock is significantly out of sync, causing the hash comparison to use stale data. SSH into the Pi and run sudo timedatectl set-ntp true to enable NTP synchronization.
• Someone else with Pi access has edited the flows directly in Node-RED's local editor. The local editor is available at the Pi's local IP on port 1880. Redeploying from the Configurator will overwrite those manual changes.

Known Issues and Limitations

• Flow snapshots are stored in Firestore and are subject to Firestore document size limits. Very large flows with many rooms and parts could approach this limit. If snapshot storage fails, the deploy itself still succeeds — the version history entry will simply be absent.
• Rollback restores the Node-RED program on the Pi but does not restore your Configurator draft to the state it was in at the time of the rolled-back deploy. You must manually update your draft to match if you want your draft and the deployed flow to be in sync.
• The 120-second deploy timeout is fixed. Very slow Pi internet connections that require large package downloads may time out during the "Installing packages" step even though the Pi is still working. If this happens, wait for the Pi to finish installing, then retry the deploy — the packages will already be present and the retry will skip the install step.
• Flow versioning retains a maximum of 20 snapshots per device. Snapshots beyond this limit are automatically removed, oldest first.

Related Documentation

• Flow Editor — wiring parts together before deploying
• Setup Wizard — completing the guided setup before your first deploy
• Device Health Dashboard — verifying your Pi is online before deploying