Skip to main content

Scenario Synchronization with Equipment

Synchronization is the step that transfers your scenarios from the database to the Logic Controller equipment via MQTT. It's an essential step for your automations to actually be executed.

Synchronization Principle​

Scenarios exist in two distinct locations:

  1. Database (DB): Where you create and modify your scenarios via the web interface
  2. Logic Controller Equipment: Where scenarios are stored and executed in real-time

Synchronization uses the MQTT protocol to transfer scenarios between these two locations.

Important

A scenario saved in the DB will NOT be executed until it has been synchronized with the equipment.

Accessing Synchronization​

Prerequisites​

Before you can synchronize, make sure that:

  • ✅ The equipment is online (status "online")
  • ✅ You have at least one created scenario in the DB
  • ✅ You have the necessary permissions (Premium or Demo subscription)

Opening the Synchronization Modal​

  1. Access your equipment's "Scenario" tab
  2. In the top right, click the "Synchronize with equipment" button
  3. The synchronization modal opens and automatically loads the scenario status
Equipment Offline

If the equipment is offline or you have no scenarios, the button will be disabled (grayed out).

Automatic Loading​

When opening the modal, the system:

  1. 📡 Sends a LIST command via MQTT to the equipment
  2. ⏱️ Waits for the equipment response (8-second timeout)
  3. 🔍 Compares DB scenarios with equipment scenarios
  4. 📊 Displays results with possible actions
MQTT Communication

Synchronization uses the following MQTT topics:

  • {MAC}/SCENARIO/CMD - Sending commands
  • {MAC}/SCENARIO/CMD/OUT - Receiving scenario list
  • {MAC}/SCENARIO/ACK - Acknowledgments
  • {MAC}/SCENARIO - Sending complete scenarios

Synchronization States​

Each scenario in the modal displays a clear visual state:

✅ Synchronized​

  • Badge: Green "Synchronized" badge with ✓ icon
  • Left border: Green
  • Meaning: The scenario is identical in DB and equipment
  • Condition: lastSyncAt exists and updatedAt ≤ lastSyncAt and active/inactive status matches
  • Available action: Delete from equipment

⚠️ To Update​

  • Badge: Orange "To update" badge with ⚠ icon
  • Left border: Orange/Yellow
  • Meaning: The scenario exists in both but was modified in the DB
  • Condition:
    • Either lastSyncAt is null (never synchronized)
    • Or updatedAt > lastSyncAt (modified since last sync)
    • Or the active/inactive status has changed
  • Available actions:
    • Update in equipment
    • Delete from equipment

❌ Not Synchronized​

  • Badge: Gray "Not synchronized" badge with ✗ icon
  • Left border: Gray
  • Meaning: The scenario exists only in the DB, not in the equipment
  • Condition: No corresponding scenario found in equipment
  • Available action: Add to equipment

🚨 Orphan Scenario​

  • Badge: Red "Not referenced" badge with ? icon
  • Left border: Red
  • Background: Slightly transparent red
  • Meaning: The scenario exists in the equipment but not in the DB
  • Possible cause:
    • Scenario deleted from DB but not yet from equipment
    • DB reset
    • Scenario created directly on equipment (rare case)
  • Available action: Delete from equipment

"To sync" Badge in List​

In the "Scenario" tab (list view), each scenario card displays an orange "To sync" badge if:

  • The scenario has never been synchronized (lastSyncAt is null)
  • The scenario was modified after the last synchronization (updatedAt > lastSyncAt)

This badge allows you to quickly see which scenarios need synchronization without opening the modal.

Synchronization Actions​

Add to Equipment​

When to use: For a scenario that exists only in the DB

Process:

  1. Click on "Add to equipment"
  2. An info toast displays: "Adding scenario [name] in progress..."
  3. The scenario is converted to MQTT WAGO format
  4. Published on topic {MAC}/SCENARIO
  5. Wait 1.5 seconds for confirmation
  6. Update lastSyncAt in the DB
  7. Success toast: "Scenario [name] added to equipment"
Tip

After creating a new scenario, remember to add it to the equipment for it to be operational.

Update in Equipment​

When to use: For a scenario that has been modified in the DB

Process:

  1. Click on "Update"
  2. An info toast displays: "Updating scenario [name] in progress..."
  3. The updated scenario is converted to MQTT WAGO format
  4. Published on topic {MAC}/SCENARIO (overwrites the old one)
  5. Wait 1.5 seconds
  6. Update lastSyncAt in the DB
  7. Success toast: "Scenario [name] updated in equipment"
Status Update

If you enable or disable a scenario, this also triggers a "To update" state because the active/inactive status must be synchronized with the equipment.

Delete from Equipment​

When to use:

  • To remove a scenario from equipment while keeping it in the DB
  • To clean up an orphan scenario

Process:

  1. Click on "Delete" or "Delete from equipment"
  2. An info toast displays: "Deleting scenario [id] in progress..."
  3. Send a DELETE command via topic {MAC}/SCENARIO/CMD
  4. Wait 1.5 seconds
  5. Update lastSyncAt to null in the DB (for non-orphan scenarios)
  6. Success toast: "Scenario [id] deleted from equipment"
Difference from Full Deletion

Deleting from equipment does NOT delete the scenario from the DB. It remains accessible and editable, but no longer executes on the equipment until you add it again.

Refresh State​

At the bottom of the modal, the "Refresh" button allows you to:

  1. Reload the current state of scenarios from the equipment
  2. Update the DB/Equipment comparison
  3. Detect new changes

When to use:

  • After performing multiple synchronizations
  • If multiple users manage the same equipment
  • To verify that actions have been applied correctly

Displayed Information​

For each scenario in the modal, you see:

  • Scenario name with icon
  • Active/inactive badge (green/gray)
  • Sync state badge (synchronized/to update/not synchronized)

Description (if present)​

  • Descriptive text of the scenario
  • Last modification date (e.g., "2 hours ago")
  • ID in equipment (e.g., "scenario_123") - only if present in equipment
  • Action buttons according to state

Error Handling​

Error: Timeout​

Message: "Timeout: Equipment did not respond to LIST command..."

Cause: Equipment did not respond within 8 seconds

Solutions:

  • Verify that equipment is online
  • Check MQTT connection
  • Ensure equipment firmware is up to date (scenarios feature supported)
  • Click on "Retry"

Error: Invalid MQTT Response​

Message: "Error processing MQTT response: [details]"

Cause: Equipment response is not in expected format

Solutions:

  • Check firmware version
  • Contact technical support
  • Click on "Retry"

Error: Equipment Reports an Error​

Message: "Equipment error: [equipment message]"

Cause: Equipment returned an ACK with "error" or "failure" status

Solutions:

  • Check equipment logs
  • Verify that scenario is compatible with equipment
  • Try deleting then recreating the scenario

Complete Synchronization Workflow​

Here's a typical synchronization workflow:

Scenario 1: New Scenario​

  1. ✏️ Create a new scenario in the canvas
  2. 💾 Save the scenario (saved to DB)
  3. 🔍 The scenario appears in the list with "To sync" badge
  4. 🔄 Open the synchronization modal
  5. ➕ Click on "Add to equipment"
  6. ✅ The scenario is now active and synchronized

Scenario 2: Modifying an Existing Scenario​

  1. ✏️ Edit an existing scenario in the canvas
  2. 🔧 Modify blocks, parameters, conditions
  3. 💾 Save modifications
  4. 🔍 The scenario now displays the "To sync" badge
  5. 🔄 Open the synchronization modal
  6. 🔁 Click on "Update"
  7. ✅ Modifications are applied to equipment

Scenario 3: Enable/Disable​

  1. 🎚️ Toggle the active/inactive switch of a scenario
  2. 🔍 The "To sync" badge appears
  3. 🔄 Open the synchronization modal
  4. 🔁 Click on "Update" to synchronize the new status
  5. ✅ Equipment enables or disables the scenario

Scenario 4: Cleaning an Orphan Scenario​

  1. 🔄 Open the synchronization modal
  2. 🔍 An orphan scenario (red) is detected
  3. 🗑️ Click on "Delete from equipment"
  4. ✅ The scenario is removed from equipment
  5. 🔄 Refresh to confirm deletion

Visual Indicators​

Border Color Codes​

  • 🟢 Green: Synchronized scenario (everything up to date)
  • 🟡 Yellow/Orange: Scenario to update (pending changes)
  • ⚪ Gray: Not synchronized scenario (never sent to equipment)
  • 🔴 Red: Orphan scenario (in equipment but not in DB)

Badge Icons​

  • ✓ (check-circle): Synchronized
  • ⚠ (exclamation-circle): To update
  • ✗ (x-circle): Not synchronized
  • ? (question-circle): Orphan / Not referenced

Technical Information​

MQTT Format​

Scenarios are converted to WAGO format before sending via MQTT:

Scenario message structure:

{
  "scenarioId": "scenario_123",
  "active": true,
  "blocks": [...],
  "connections": [...],
  "parameters": [...]
}

LIST command:

{
  "command": "LIST"
}

DELETE command:

{
  "command": "DELETE",
  "scenarioId": "scenario_123",
  "confirm": true
}

Change Detection​

The system automatically detects that a scenario has changed if:

  1. lastSyncAt is null (never synchronized)
  2. updatedAt > lastSyncAt (modified since last sync) - comparison to the second
  3. isActive (DB) ≠ active (equipment) - status has changed

Best Practices​

For effective synchronization:

✅ Synchronize after each important modification: Don't let changes accumulate ✅ Check "To sync" badges: Regularly check the scenario list ✅ Use "Refresh": Before and after a series of synchronizations ✅ Clean up orphans: Delete orphan scenarios to avoid confusion ✅ Check equipment status: Ensure it's "online" before synchronizing ✅ Wait for confirmation: Toasts indicate success or failure of each action ✅ Test after sync: Verify that the scenario executes correctly

Limitations and Constraints​

Communication Delay​

  • Timeout: 8 seconds for LIST command
  • Post-action delay: 1.5 second wait after each command
  • These delays are necessary for MQTT communication and equipment processing

Firmware​

  • The feature requires up-to-date firmware on the equipment
  • Older firmware may not support scenario commands
  • Regularly check for available firmware updates

MQTT Connection​

  • Equipment must be connected to MQTT broker
  • An unstable connection can cause synchronization failures
  • In case of problems, check equipment network settings

Troubleshooting​

"Synchronize" Button is Disabled​

Check:

  • Is the equipment online?
  • Do you have at least one scenario created?
  • Do you have necessary permissions (Premium/Demo)?

Actions:

  1. Check equipment state (must be "online")
  2. Check MQTT connection in settings
  3. Restart equipment if necessary
  4. Update equipment firmware

Scenario Not Executing After Synchronization​

Actions:

  1. Verify scenario is enabled (switch ON)
  2. Open modal and check state (must be "Synchronized")
  3. Check "Logs" tab to see executions
  4. Verify sensors used exist and work
  5. Test the scenario with "Test" button

Orphan Scenarios Appear​

Possible causes:

  • Deletion of a scenario from DB without deleting it from equipment
  • DB reset
  • Equipment migration

Solution:

  • Delete orphans from equipment via "Delete from equipment" button

Conclusion​

MQTT synchronization is the bridge between your web configuration and real-time execution on the equipment. By understanding the different states and following best practices, you'll maintain perfect consistency between your DB scenarios and those active in the field.

You've Now Mastered Scenarios!

You know how to create, configure, and synchronize scenarios. Don't hesitate to experiment and create complex automations adapted to your needs!