Troubleshooting Devices
This page covers common device issues, how to interpret health indicators, and the tools available to diagnose problems.
Understanding hardware health indicators
The Overview tab shows a Hardware card with real-time health metrics. Each metric has a color-coded status indicator:
Disk usage
| Color | Meaning |
|---|---|
| 🟢 Green | More than 60% of disk space is free |
| 🟡 Yellow | 30–60% of disk space is free |
| 🔴 Red | Less than 30% of disk space is free |
If disk usage is high, check whether a skill is writing large amounts of data or logs to the device. You may need to clear data or update the skill configuration to reduce disk output.
CPU usage
| Color | Meaning |
|---|---|
| 🟢 Green | CPU usage below 30% (15-minute average) |
| 🟡 Yellow | CPU usage between 30–60% |
| 🔴 Red | CPU usage at or above 60% |
Sustained high CPU usage may indicate a skill is CPU-bound or is not functioning correctly. Check the Skill Logs for errors.
Memory usage
| Color | Meaning |
|---|---|
| 🟢 Green | Less than 30% of memory in use |
| 🟡 Yellow | 30–60% of memory in use |
| 🔴 Red | More than 60% of memory in use |
Internal temperature
Temperature thresholds vary by device model. See Device Models for model-specific values.
| Color | Meaning |
|---|---|
| 🟢 Green (Cool) | Temperature is within normal range |
| 🟡 Yellow (Warm) | Temperature is elevated — check ventilation |
| 🔴 Red (Hot) | Temperature is dangerously high — take action immediately |
If a device is overheating:
- Ensure the device has adequate ventilation and is not enclosed without airflow.
- Check that nothing is blocking the device's vents or heat sinks.
- If the problem persists, contact support.
Audio connection
Shows whether a headphone jack or audio device is connected to the device. Displays Connected or Disconnected.
Device is offline
If a device shows an Offline status, try the following steps in order:
- Verify power — Confirm the device is powered on and the power LED is lit.
- Check network connection — Ensure the device's network cable is connected or Wi-Fi is configured. The device requires outbound internet access on port 443.
- Check for proxy issues — If your network requires an HTTP proxy, ensure the proxy URL is configured on the device.
- Wait for reconnection — If the device recently rebooted or lost power momentarily, it may take a few minutes to reconnect.
- Refresh device details — Use the Refresh Details button in the Network card to request a fresh telemetry update from the device.
"Unknown" status after enrollment
A newly enrolled device shows Unknown status until it sends its first telemetry report to the portal. This is normal. Wait a few minutes after enrollment for the device to come online. If it stays Unknown for more than 10–15 minutes:
- Check that the device has a working internet connection.
- Check that the enrollment completed successfully (the device was claimed before the 5–7 minute enrollment window expired).
Refreshing device details
The Network Connections card in the Overview tab has a Refresh Details button. Clicking it sends a ping command to the device, which causes the device to immediately push a fresh telemetry report to the portal (updated CPU, memory, disk, temperature, IP address, etc.).
This is useful when you need current hardware stats and don't want to wait for the next scheduled update.
Rebooting a device
To reboot a device:
- Open the device detail view.
- Click the Overview tab.
- Click Reboot Device in the Hardware card.
- Confirm the reboot.
The device will restart and reconnect automatically. Status will briefly show Offline during the reboot and return to Online within a few minutes.
The Reboot Device button is only active when the device is Online. If the device is offline, you will need to physically power-cycle it.
Accessing the on-device control panel (EWS)
The EWS (Embedded Web Server) button in the device Overview tab opens a secure browser-based connection to the device's on-board control panel. This is useful for:
- Reviewing device-level configuration
- Checking device-side diagnostic information
- Advanced network configuration
The EWS connection is tunneled securely through the portal and expires after 1 hour. A progress indicator in the EWS window shows the remaining time. If the tunnel expires, close and reopen it.
The device must be Online for the EWS to open. If the device is offline, the EWS button will not function.
Skill is not running or behaving incorrectly
- Check the Skills tab in the device detail view — verify the skill is deployed and shows an active status.
- Open the Device Logs tab and select Skill logs for the affected skill. Look for error messages or crash reports.
- If the skill is crashing, check that all required inputs and environment variables are configured correctly.
- Try restarting the skill from the Skills tab if the option is available.
Deployment is stuck or not syncing
The portal tracks whether each device's deployed configuration is up to date. If a device shows a "syncing" or "pending" indicator in the Devices list:
- Check that the device is Online.
- Wait a few minutes — sync operations can take time depending on the size of the skill image being deployed.
- Ensure the workflow is synced on the workflows page.
Firmware update failed
If a firmware update shows an Error status:
- Verify the device is online and connected.
- Retry the update from the device detail view.
- Check the Device Logs for error messages that may indicate the cause (e.g., insufficient disk space, network interruption during download).
See Firmware for full details on the update process and status meanings.
Getting help
If you have exhausted the steps above and the device is still not functioning correctly:
- Use the Device Logs tab to export logs (click Download Logs) and include them in your support request.
- Note the device serial number, model, and current firmware version from the Overview tab.
- Contact support through the portal or at your organization's support channel.