Skip to main content

Product Prerequisites

Some products require prerequisites before they can operate normally. Prerequisites are setup steps that ensure products are properly configured, connected, and calibrated.

What Are Prerequisites?

Prerequisites are actions that must be completed before a product can function correctly. They're defined at the model level and guide you through specific configuration flows (e.g., connecting a gateway to Wi-Fi, setting motor limits).

When Prerequisites Are Required​

You'll encounter prerequisites:

  • After adding a product – The app prompts you to complete required steps
  • Before controlling a model – If a model hasn't completed its prerequisites, you'll be prompted each time you try to control it
  • In Product Settings – You can view and complete prerequisites manually

Prerequisite Properties​

Each prerequisite has:

  • Prerequisite Flow: A specific sequence of steps to complete (e.g., connect_gateway_wifi_ethernet, set_motor_limits)
  • Skippable: Whether you can skip this step (some are mandatory)
  • Online Required: Whether the device must be online to complete this step
  • Completion Status: Whether the prerequisite has been completed
tip

Prerequisites that require the device to be online are automatically skipped in Offline Mode and can be completed later when devices come online.

Supported Prerequisite Flows​

TWIST supports the following prerequisite flows:

1. Connect Gateway to Internet​

Flow ID: connect_gateway_wifi_ethernet

Purpose: Connect the gateway to the internet via Ethernet or Wi-Fi

When: Required when adding a gateway to an installation

Skippable: Yes

Online Required: No (device comes online as part of this flow)

Steps:​

  1. Choose Connection Method
    • You'll be asked to choose between Ethernet or Wi-Fi

Option A: Ethernet Connection​

  1. Connect Ethernet Cable

    • Connect an Ethernet cable to the gateway
    • Ensure the cable is connected to your router/network

  2. Power the Gateway

    • Plug in the gateway
    • The app monitors the middleware to check if the gateway comes online

  3. Wait for Connection

    • When the gateway successfully connects, all 3 LEDs on the gateway will blink cyan
    • The app detects the gateway is online and completes the flow

Option B: Wi-Fi Connection​

  1. Prepare the Gateway

    • Ensure the gateway is powered on
    • Ensure the gateway is within range of your Wi-Fi router
    • Important: The gateway must NOT be connected via Ethernet

  2. Connect via Bluetooth

    • The app establishes a direct connection to the gateway using Bluetooth Low Energy (BLE)
    • Ensure Bluetooth is enabled on your phone

  3. Select Wi-Fi Network

    • The app requests available Wi-Fi SSIDs from the gateway
    • Select your Wi-Fi network from the list

  4. Enter Wi-Fi Credentials

    • Enter your Wi-Fi password
    • Tap Connect

  5. Wait for Connection

    • The gateway connects to your Wi-Fi network
    • When successful, all 3 LEDs on the gateway will blink cyan
    • The flow is complete

2. Set Motor Limits​

Flow ID: set_motor_limits

Purpose: Configure the upper and lower limit positions for motors

When: Required for motors that support manual limit configuration (e.g., protocol-based shutters)

Skippable: Yes

Online Required: Yes (automatically skipped in Offline Mode)

Applies To: PB (Protocol-Based) Shutter models

Why Set Motor Limits?

Motor limits define the upper (retracted) and lower (extended) positions of a motor. Setting these ensures the motor stops at the correct positions and doesn't over-extend or retract.

Steps:​

This flow guides you through setting the upper and lower limits for each motor model in the product.

Step 1: Set Upper Limit Position​

  1. Move Motor to Upper Position

    • Use the control buttons to move the motor:
      • Up / Retract: Move motor upward (or retract)
      • Down / Extend: Move motor downward (or extend)
      • Stop: Stop motor movement
      • Step Up: Move motor up by a small increment (for fine-tuning)
      • Step Down: Move motor down by a small increment (for fine-tuning)

  2. Fine-Tune the Position

    • Use Step Up and Step Down to adjust the motor to the exact upper position

  3. Store Upper Limit

    • Tap Store Upper Limit or Save
    • The motor will provide physical feedback by moving up and back one step

Step 2: Set Lower Limit Position​

  1. Move Motor to Lower Position

    • Use the same control buttons (Up, Down, Stop, Step Up, Step Down)

  2. Fine-Tune the Position

    • Adjust the motor to the exact lower position

  3. Store Lower Limit

    • Tap Store Lower Limit or Save
    • The motor will provide physical feedback

Step 3: Test Position Control (Optional)​

  1. Set Motor to a Specific Position

    • Use the position slider to move the motor to any position between 0% and 100%
    • Test that the motor moves correctly between the limits

  2. Skip or Complete

    • You can skip testing and finalize the prerequisite
    • Or test multiple positions before completing

Additional Options:​

  • Change Motor Direction: If the motor moves in the wrong direction (up command moves it down), you can reverse the direction

    • Look for a Change Motor Direction or Reverse option in Step 1
    • This changes the motor direction parameter

  • Restart Process: At any time, you can restart the limit-setting process

    • This will clear the stored limits and return to Step 1

3. Automatic Motor Calibration​

Flow ID: automatic_calibrate_motor

Purpose: Automatically calibrate the motor transition time

When: Required for motors that support automatic calibration (e.g., current-based shutters)

Skippable: Yes

Online Required: Yes (automatically skipped in Offline Mode)

Applies To: CB (Current-Based) Shutter models

Why Calibrate Motors?

Calibration determines how long it takes for the motor to move from fully retracted to fully extended. This allows the system to accurately position the motor at any point (e.g., 50% open).

Steps:​

This flow allows you to calibrate each motor model in the product.

1. Start Calibration​

  • For each motor model:
    • Tap Start Calibration or Calibrate
    • The motor will automatically move through its full range
    • The calibration process takes some time (the motor moves up and down)
Calibrate Multiple Motors

You can start calibration for multiple motors simultaneously without waiting for the first to finish. The app monitors each motor's progress.

2. Monitor Calibration Progress​

  • The app displays the calibration status for each motor
  • Wait for the calibration to complete
  • When done, the motor's status changes to "Calibrated"

3. Test and Adjust Direction (Optional)​

Before or after calibration, you can:

  • Test Motor Direction:

    • Use Up, Down, and Stop buttons
    • Verify the motor moves in the correct direction

  • Change Motor Direction:

    • If the motor moves incorrectly (up command moves it down), change the direction
    • Look for Change Motor Direction or Reverse option
    • This adjusts the motor direction parameter
note

You cannot change direction while calibration is in progress.

4. Complete Prerequisite​

  • Once all motors are calibrated, the prerequisite is complete
  • You can now control the motors with position accuracy

Managing Prerequisites​

Viewing Prerequisites​

  • During Product Setup: Prerequisites are displayed automatically after adding a product
  • In Product Settings:
    1. Go to Products → Select Product → Settings
    2. View Prerequisites or Setup section
    3. See which prerequisites are complete and which are pending

Completing Prerequisites Later​

If you skip a prerequisite:

  • You'll be prompted to complete it each time you try to control the affected model
  • You can complete it manually in Product Settings

Completing Skipped Offline Prerequisites​

If a prerequisite was skipped because the device was offline:

  • Complete it once the device comes online
  • Go to Product Settings → Prerequisites
  • Follow the guided flow

Expected Result​

After completing prerequisites:

  • The product functions normally
  • You can control models without repeated prompts
  • Prerequisites are marked as "Complete" in Product Settings

Troubleshooting​

Gateway Won't Connect (Ethernet)​

  • Check cable: Ensure the Ethernet cable is securely connected
  • Verify network: Ensure your router/network is working
  • Check LEDs: Look for LED indicators on the gateway
  • Wait longer: Connection may take a minute or two

Gateway Won't Connect (Wi-Fi)​

  • Check Bluetooth: Ensure Bluetooth is enabled on your phone
  • Check Wi-Fi password: Verify you entered the correct credentials
  • Check range: Ensure the gateway is within range of your Wi-Fi router
  • Restart gateway: Power cycle the gateway and try again
  • Ethernet conflict: Ensure the gateway is NOT connected via Ethernet while setting up Wi-Fi

Motor Moves in Wrong Direction​

  • Use Direction Change: During the prerequisite flow, use the Change Motor Direction option
  • Restart if needed: If you've already completed the prerequisite, restart the flow to change direction

Motor Calibration Fails​

  • Ensure motor can move freely: Check for obstructions
  • Restart calibration: Try the calibration process again
  • Check power: Ensure the motor is properly powered
  • Contact support: If calibration repeatedly fails, contact technical support

Can't Complete Prerequisite (Device Offline)​

  • Check device status: Ensure the device is powered and online
  • Check gateway: Ensure the gateway is connected
  • Complete later: Some prerequisites can be completed once the device is online

Next Steps​

After completing prerequisites:

  1. Set Mandatory Parameters – Configure any required settings
  2. Link Products – Connect products that interact
  3. Control Products – Start using your products