Troubleshooting

This guide helps you troubleshoot common issues with your TWIST installation. Issues are organized by category for quick reference.

Quick Diagnostics

Before diving into specific troubleshooting:

1. Check gateway status: Ensure your gateway is online (Dashboard or Products → Gateway)
2. Check device status: Verify devices are powered and online (Products → Select Product → Settings → Devices)
3. Check internet: Ensure your gateway has internet connectivity
4. Restart the app: Close and reopen the TWIST app

---

Connectivity Issues

Gateway Won't Connect to Internet

Symptoms:

• Gateway shows as offline
• Can't control products
• Weather data not updating

Solutions:

For Ethernet Connection:

1. Check the Ethernet cable is securely connected to both the gateway and router
2. Verify your router is working and has internet
3. Look for LED indicators on the gateway:
   • All 3 LEDs blinking cyan: Successfully connected
   • Other patterns: Connection issue
4. Try a different Ethernet cable
5. Try a different port on your router
6. Power cycle the gateway (unplug, wait 10 seconds, plug back in)

For Wi-Fi Connection:

1. Ensure the gateway is within range of your Wi-Fi router
2. Check that you entered the correct Wi-Fi password
3. Ensure the gateway is NOT connected via Ethernet (this can conflict with Wi-Fi setup)
4. Verify your Wi-Fi network is 2.4GHz or 5GHz (check router settings)
5. Restart your Wi-Fi router
6. Power cycle the gateway
7. Re-run the Wi-Fi setup prerequisite (see Product Prerequisites)

---

Device Appears Offline

Symptoms:

• Product shows as offline in Product Settings
• Can't control the product
• Product doesn't respond to commands

Solutions:

1. Check power:

   • Ensure the device is plugged in and powered on
   • Check circuit breakers and power outlets
   • Verify power cables are secure

2. Check range:

   • Devices must be within range of the gateway (typically 30-50 meters indoors)
   • Metal structures, thick walls, and interference can reduce range
   • Consider adding a repeater if devices are far from the gateway

3. Check gateway status:

   • Ensure the gateway itself is online
   • If the gateway is offline, fix that first

4. Power cycle the device:

   • Turn off power to the device
   • Wait 10 seconds
   • Turn power back on
   • Wait 1-2 minutes for the device to reconnect

5. Check mesh network:

   • All devices in the installation communicate via a mesh network
   • If one device goes offline, it may affect others
   • Power cycle all devices in the product

6. Re-add the device (last resort):

   • If the device remains offline, try removing and re-adding it
   • Go to Products → Select Product → Settings → Devices → Remove Device
   • Add the device again using discovery or QR code scan

---

Products Not Responding to Commands

Symptoms:

• Product shows as online but doesn't respond
• Commands sent but no action occurs
• Delays in product response

Solutions:

1. Check prerequisites:

   • Ensure all prerequisites are complete (see Product Prerequisites)
   • Some products won't respond until prerequisites are finished

2. Check gateway connectivity:

   • Verify the gateway is online and has internet

3. Check device status:

   • Go to Products → Select Product → Settings → Devices
   • Verify all devices in the product are online

4. Check network congestion:

   • If many commands are sent simultaneously, there may be a delay
   • Wait a few seconds and try again

5. Refresh the app:

   • Pull down to refresh the screen
   • This ensures you have the latest device status

6. Restart the app:

   • Close and reopen the TWIST app

7. Power cycle the device:

   • Turn off power to the device, wait 10 seconds, turn back on

---

Pairing and Discovery Issues

Discovery Finds No Devices

Symptoms:

• Gateway discovery runs but finds no devices
• "No devices found" message

Solutions:

1. Check device power:

   • Ensure all devices are powered on
   • Check circuit breakers and outlets

2. Check device range:

   • Devices must be within range of the gateway for discovery
   • Bring devices closer to the gateway temporarily

3. Check pairing mode:

   • Some devices require pairing mode to be discovered
   • Refer to manufacturer instructions for entering pairing mode

4. Check gateway status:

   • Ensure the gateway is online and connected

5. Wait and retry:

   • Discovery can take 30-60 seconds
   • Wait for the timeout and try again

6. Restart discovery:

   • Stop discovery and start it again
   • Give devices time to respond

7. Use offline mode:

   • If discovery continues to fail, use offline mode (QR code scanning)
   • Add devices by scanning QR codes
   • Configuration will be applied when devices come online

---

Device QR Code Won't Scan

Symptoms:

• QR code scanner doesn't recognize the code
• Scanner app doesn't open

Solutions:

1. Ensure good lighting:

   • QR codes scan best in well-lit conditions
   • Avoid glare or shadows on the QR code

2. Hold steady:

   • Keep your phone steady at a reasonable distance from the QR code
   • Don't move the phone while scanning

3. Check camera permissions:

   • Ensure the TWIST app has camera access
   • Go to device Settings → Apps → TWIST → Permissions → Camera → Enable

4. Clean the QR code:

   • Ensure the QR code isn't damaged, dirty, or obscured
   • Wipe the code with a clean cloth

5. Clean camera lens:

   • Wipe your phone's camera lens

6. Try manual entry (if supported):

   • Some apps allow manual entry of the device ID
   • Enter the device ID printed near the QR code

---

Device Already Belongs to Another Installation

Symptoms:

• "Device already registered" error
• Can't add device to your installation

Solutions:

1. Remove from previous installation:

   • The device must be removed from its current installation first
   • Contact the previous installation owner
   • Or use device reset procedure (refer to manufacturer instructions)

2. Factory reset the device:

   • Refer to manufacturer instructions for factory reset
   • This removes the device from all installations
   • Re-add the device to your installation

3. Contact support:

   • If you can't remove the device, contact TWIST support
   • Provide the device ID and installation details

---

Product Configuration Issues

Can't Complete Prerequisites

Symptoms:

• Prerequisite flow won't complete
• "Device offline" error during prerequisite

Solutions:

1. Check device status:

   • Ensure the device is online (Product Settings → Devices)
   • Prerequisites requiring online access won't work if the device is offline

2. Use offline mode (if applicable):

   • Some prerequisites can be skipped in offline mode
   • Complete them later when devices come online

3. Retry the prerequisite:

   • Go to Product Settings → Prerequisites
   • Restart the prerequisite flow

4. Check internet connectivity:

   • For gateway connection prerequisites, ensure you have internet
   • Verify Wi-Fi password or Ethernet connection

5. Refer to detailed guides:

   • See Product Prerequisites for step-by-step instructions

---

Motor Moves in Wrong Direction

Symptoms:

• Pressing "Up" moves motor down
• Pressing "Open" closes the product

Solutions:

1. Change motor direction:

   • During prerequisites (set limits or calibration), use the "Change Motor Direction" option
   • This reverses the motor direction parameter

2. Restart prerequisite:

   • If you've already completed the prerequisite, restart it
   • Go to Product Settings → Prerequisites → Restart

3. Check motor wiring (advanced):

   • If direction change doesn't work, the motor may be wired incorrectly
   • Contact the installer or manufacturer

---

Motor Position Inaccurate

Symptoms:

• Motor shows 50% but is fully open/closed
• Position slider doesn't match physical position

Solutions:

1. Recalibrate the motor:

   • Go to Product Settings → Prerequisites → Calibrate Motor
   • Follow the calibration flow

2. Reset motor limits (for PB shutters):

   • Go to Product Settings → Prerequisites → Set Motor Limits
   • Restart the limit-setting process

3. Check for obstructions:

   • Ensure the motor can move freely without obstructions

4. Check motor type:

   • Motors without feedback (some models) don't support position tracking
   • These motors only show state (stopped, running up, running down)

---

Scene and Routine Issues

Scene Doesn't Set Products Correctly

Symptoms:

• Scene activates but products don't reach expected states
• Some products in scene don't respond

Solutions:

1. Check product status:

   • Ensure all products in the scene are online
   • Go to Products → Select Product → Settings → Devices

2. Re-edit the scene:

   • The scene may have captured incorrect states
   • Edit the scene and re-save with correct states
   • See Create Scenes

3. Test products manually:

   • Control products manually first to ensure they work
   • Then recreate the scene

4. Check prerequisites:

   • Ensure all products have completed prerequisites

5. Recreate the scene:

   • Delete the scene and create it again from scratch

---

Routine Doesn't Trigger

Symptoms:

• Routine never runs
• Time-based routine doesn't trigger at set time
• Event-based routine doesn't respond to events

Solutions:

General:

1. Check routine status:

   • Ensure the routine is enabled (toggle is ON)
   • Go to Routines → Select Routine → Enable

2. Check trigger condition:

   • Verify the trigger condition was actually met
   • For time-based: Check device time and timezone
   • For sensor-based: Check sensor is working and threshold was crossed

3. Check product status:

   • Ensure all products in the routine are online

4. Check gateway status:

   • Ensure the gateway is online

Time-Based Routines:

1. Check installation timezone:

   • Verify the installation location is set correctly
   • Go to Settings → Installations → Select Installation → Edit Location

2. Check device time:

   • Ensure your device time is correct

3. Check sunrise/sunset calculation:

   • Sunrise/sunset times are based on installation location
   • Verify location is accurate

Sensor-Based Routines:

1. Check sensor status:

   • Verify the sensor is working (check in Product Settings)
   • View real-time sensor data

2. Adjust threshold:

   • Threshold may need adjustment (e.g., wind speed > 25 km/h instead of > 30 km/h)

Button-Based Routines:

1. Check button status:

   • Verify the button is working (press button and check state in Product Settings)

2. Check button availability:

   • Ensure the button isn't already used for other functionality

---

Routine Triggers but Actions Fail

Symptoms:

• Routine runs but products don't change state
• Notification says routine failed

Solutions:

1. Check product status:

   • Ensure all products in the routine are online

2. Check prerequisites:

   • Ensure all products have completed prerequisites

3. Check network:

   • Verify gateway and devices are connected

4. Review routine configuration:

   • Verify the routine actions are configured correctly
   • Edit the routine and re-save

5. Check activity log (if available):

   • Go to Routines → Activity Log
   • Check for error messages

---

Notification Issues

Not Receiving Notifications

Symptoms:

• No push notifications appear
• Notifications not showing on lock screen

Solutions:

1. Check OS permissions:

   • Go to device Settings → Apps → TWIST → Notifications
   • Ensure notifications are enabled

2. Check app settings:

   • Open TWIST app → Settings → Notifications
   • Ensure notifications are enabled for desired events

3. Check network:

   • Ensure your device has internet connectivity
   • Push notifications require network access

4. Check Do Not Disturb:

   • Ensure Do Not Disturb is not enabled (TWIST or device settings)

5. Restart app:

   • Close and reopen the TWIST app

6. Reinstall app (last resort):

   • Uninstall and reinstall the TWIST app
   • Sign in again and re-enable notifications

See Notifications for detailed setup.

---

App Issues

App Crashes or Freezes

Symptoms:

• App closes unexpectedly
• App becomes unresponsive

Solutions:

1. Restart the app:

   • Close the app completely
   • Reopen it

2. Restart your device:

   • Turn your device off and back on

3. Update the app:

   • Check the app store for updates
   • Install the latest version

4. Clear app cache:

   • Go to Settings → App → Clear Cache
   • This doesn't delete your data

5. Check device storage:

   • Ensure your device has sufficient storage space
   • Delete unused apps or files if needed

6. Reinstall the app:

   • Uninstall and reinstall the TWIST app
   • Sign in again

7. Report the issue:

   • If crashes persist, report via Settings → Help → Report Issue
   • Include details about when the crash occurs

---

Can't Sign In

Symptoms:

• "Incorrect username or password" error
• Sign-in button doesn't respond

Solutions:

1. Check credentials:

   • Verify you're entering the correct email and password
   • Check for typos

2. Reset password:

   • Use "Forgot Password" to reset your password
   • Check your email for the reset link

3. Check internet:

   • Ensure your device has internet connectivity

4. Update app:

   • Check for app updates in the app store

5. Try portal:

   • Try signing in via the web portal
   • If successful, the issue is with the app

6. Contact support:

   • If you still can't sign in, contact TWIST support

See Accounts & Sign-in for detailed instructions.

---

Dashboard Not Updating

Symptoms:

• Product states don't update
• Weather data is stale
• Dashboard shows old information

Solutions:

1. Pull to refresh:

   • Swipe down on the Dashboard to refresh

2. Check internet:

   • Ensure your device has internet connectivity

3. Check gateway status:

   • Verify the gateway is online

4. Restart app:

   • Close and reopen the TWIST app

5. Check active installation:

   • Verify you have the correct installation selected

---

Getting Additional Help

If you've tried the troubleshooting steps and still have issues:

Check Documentation

• Review relevant sections in this documentation
• See specific guides for Products, Scenes, Routines

Contact Support

• Go to Settings → Help → Contact Support
• Provide details:
  • Installation name
  • Product/device affected
  • What you've tried
  • Error messages or screenshots

Report a Bug

• Go to Settings → Help → Report Issue
• Include steps to reproduce the issue

Community Forum

• Visit the TWIST community forum (if available)
• Search for similar issues
• Ask questions and get help from other users

---

Preventive Maintenance

To avoid issues:

1. Keep app updated: Regularly update the TWIST app
2. Keep firmware updated: Install firmware updates when prompted
3. Monitor device status: Periodically check that all devices are online
4. Test routines: Verify routines are working as expected
5. Check gateway connectivity: Ensure the gateway has stable internet
6. Backup configuration: Some systems allow exporting configuration (check with support)
7. Document your setup: Keep notes on your scenes, routines, and product configurations