Documentation
TutorialsCommunity
  1. ALPON
  2. ALPON X4

Troubleshooting

Diagnose and resolve common issues with the ALPON X4 edge computer. Fix connectivity, boot, and hardware-related problems.

Troubleshooting

Diagnostic reference for the ALPON X4 industrial edge IoT computer: power, LEDs and boot, connectivity (LTE Cat 4, Wi-Fi, dual Ethernet), the GPIO Add-on port and USB, ALPON X4 OS, and the ALPON Cloud agent. Each issue lists the symptom, possible causes, and recommended checks.

Raspberry Pi CM4 LTE Cat 4 Dual Ethernet ALPON X4 OS
ALPON X4 · Reference · Troubleshooting · Power, LEDs, connectivity, GPIO, OS, and ALPON Cloud
How do I troubleshoot the ALPON X4?

Start from the physical layer and move up. Verify power first (15 V / 1.8 A (27 W) USB-C PD, DC 12–30 V for full peripheral functionality, or optional PoE+ within its 25 W budget), confirm the Power and Connection LEDs report a healthy state, check network links (LTE Cat 4, Wi-Fi, ETH/G, ETH) in that order, verify the GPIO Add-on rail is enabled with GPIO 21, and finally inspect ALPON X4 OS logs with journalctl -xe.

Before you troubleshoot

Start with a known-good 15 V / 1.8 A (27 W) USB-C PD adapter or a 12–30 V DC supply on the terminal block rated for the 27 W peak. Use only one power input. The DC rating is 9–30 V, but inputs below 12 V restrict peripheral functionality. A 5 V source is not a supported full-function supply; whether a device boots at low voltage is not a reliable diagnostic. See Specifications for detailed limits.

LED reference

The ALPON X4 surfaces device health on four front-panel LEDs: Power, Connection, Cellular, and a user-driven Programmable RGB. Read these indicators first; they narrow most issues to a single category in the accordion below.

White Green Blue Amber / Yellow Red Off
Power LED
Solid white Power is present. This indicator alone does not confirm that the OS has completed booting.
Off No valid power input detected. Verify the USB-C PD adapter, the DC terminal wiring, or the PoE+ injector.
Connection LED
Solid green Device is online and reachable in ALPON Cloud. No action needed.
Off Disconnected from ALPON Cloud. Check the configured uplink, LTE antennas, and cloud registration, or connect ETH/G to an upstream router. Boot and provisioning duration depend on connectivity and service availability.
Cellular LED
Blue Strong LTE signal. Throughput should track the LTE Cat 4 envelope (up to 150 Mbps DL / 50 Mbps UL, theoretical).
Amber / Yellow Moderate LTE signal. Reposition the device or attach the optional IP67 outdoor antenna for marginal coverage areas.
Red Poor or no LTE signal, or the eSIM profile has not registered. Hand-tighten both LTE antennas on the SMA connectors and verify the active profile.
Programmable RGB LED
User-defined Driven entirely by user code through the TCA6408A I/O expander on I2C1 at address 0x20. Sixfab system services do not touch it.

Common issues

Each row below is one symptom. Click a row to open it; the body covers what you see, why it may happen, and recommended checks. Rows are colour-coded by category, with the dot, the category pill, and the left rail all matching, so you can scan the list by category at a glance.

Power

The device does not power on (no LEDs)

Symptom

The Power LED stays off after power is connected.

Cause

Possible causes include an unsuitable or failed adapter, cable, or DC connection. A 5 V USB source does not meet the documented full-function supply requirement; do not infer a hardware failure solely from behavior on that source.

Fix

  1. Use the 27 W USB-C PD adapter shipped with the device.
  2. If unavailable, disconnect the USB-C supply and wire the DC terminal block to a 12–30 V DC supply rated for at least 27 W (for example 12 V / 2.5 A or 24 V / 1.25 A).
  3. Confirm wire polarity on the screw terminal: observe the + / − markings on the housing.
  4. Try a different USB-C cable. Long or low-quality cables often drop PD negotiation.
Power

The device boots but USB ports, GPIO 5 V rail, and HDMI are dead

Symptom

The Raspberry Pi CM4 comes up and Ethernet links, but USB devices are not detected, the GPIO Add-on 5 V rail is offline, the HDMI output is blank, and the Programmable RGB LED is dark.

Cause

An input below 12 V can put the ALPON X4 in Restricted Mode, disabling peripheral functionality. A running host or network link does not prove the peripheral power rails are available.

Fix

  1. Disconnect the current power source and use the supported 15 V / 1.8 A (27 W) USB-C PD adapter or a 12–30 V DC supply rated for the workload.
  2. For long DC cable runs, prefer a 24 V adapter with thicker conductors to compensate for voltage drop.
  3. After restoring supported power, check the peripherals again. If they remain unavailable, shut down safely and power-cycle with the known-good source; contact support if the problem persists.
Restricted Mode is by design

Below 12 V, USB, the GPIO Add-on 5 V rail, HDMI, and the Programmable RGB LED are restricted. The 9–30 V DC rating is not a full-function range. Restore 12–30 V at the DC input or the documented 15 V USB-C PD supply; low-voltage network reachability is not guaranteed.

Power

The device resets or throttles under sustained load

Symptom

The Raspberry Pi CM4 logs voltage or thermal warnings during peak workloads and occasionally reboots.

Cause

The supply or cable may not sustain the workload, or airflow around the heatsink may be obstructed. Optional PoE+ delivers up to 25 W and cannot cover the documented 27 W simultaneous system peak.

Fix

  1. Check the supply rating and voltage at the device under load. If using PoE+, reduce peripheral load or switch to a supported DC/USB-C PD source; disconnect the old input first.
  2. Keep airflow around the cooling surface unobstructed. Consult Power & Mounting for installation guidance and Sixfab for verified clearances.
  3. Verify with vcgencmd get_throttled that the Raspberry Pi CM4 is not hitting the under-voltage bit.
Hardware

The device boots in a reset loop

Symptom

The Raspberry Pi CM4 starts and powers down on a fixed interval without reaching a usable state.

Cause

The hardware watchdog (SW1) is enabled but no userspace service is feeding it, so the watchdog hard-resets the device on its timeout interval.

Fix

  1. Disconnect all power from the device.
  2. Lift the silicone cap on the rear face and move SW1 to ON to disable the watchdog while you finish bring-up.
  3. Reapply power and verify the device stays up. Configure exactly one heartbeat owner: the system watchdog daemon or an application replacing it, never both. Disconnect power before moving SW1 back to OFF after that owner is ready.
Toggle switches with the device off

Always disconnect all power before flipping SW1 (Watchdog) or SW2 (Boot/Burn). Changing SW2 while powered can corrupt the Raspberry Pi CM4 eMMC.

Power

PoE+ does not power the device

Symptom

The PoE injector is connected to the ETH/G port, link comes up on the switch, but the ALPON X4 does not power on.

Cause

The injector is legacy IEEE 802.3af instead of 802.3at Class 4, the cable is connected to the wrong port, or the SKU does not include the optional PoE module.

Fix

  1. Confirm the SKU is the PoE variant. The PoE module is a factory option and cannot be field-added.
  2. Use an IEEE 802.3at Class 4 injector that delivers up to 25 W on the ETH/G port only.
  3. Check the injector or switch diagnostics according to its manual. The 25 W delivered budget cannot cover the 27 W system peak; reduce peripheral load or use DC/USB-C PD for peak workloads.
  4. If the SKU does not include PoE, disconnect PoE and use USB-C PD or the DC terminal block. Use only one power input.
Connectivity

The Cellular LED is red or yellow

Cause

Weak LTE signal, missing or loose antenna, or the eSIM (eUICC) profile has not yet activated on the local network.

Fix

  1. With power disconnected, hand-tighten both antennas on the SMA connectors labeled L (LTE Main and LTE Diversity). The Wi-Fi antenna uses RP-SMA and belongs on W, not an LTE port.
  2. Reposition the antennas away from metal panels and dense walls before retesting.
  3. For known marginal sites, attach the optional IP67 outdoor antenna (3-meter cabled combination antenna with surface mount).
  4. In ALPON Cloud, open the device's eSIM management panel and verify the active profile is the one the local carrier provisions.
  5. Read RSRP and RSRQ from the modem:
    terminal shell 
    mmcli -L
mmcli -m 0 --signal-get
Connectivity

The eSIM does not register on any network

Symptom

The Cellular LED stays red. mmcli -m 0 reports registration: searching indefinitely.

Cause

No active eSIM profile is selected, the active profile has been disabled remotely, or the device is in a region not covered by the current profile.

Fix

  1. In ALPON Cloud, open the device's eSIM panel and select an active profile matching the deployment country.
  2. Confirm plan activation and country coverage with Sixfab or the profile provider. Do not attempt a physical SIM installation without model-specific guidance from Sixfab.
  3. Reboot the device so ModemManager re-attaches with the new profile.
  4. For multi-region fleets, enable roaming on the active profile in ALPON Cloud.
Connectivity

Ethernet does not link or shows the wrong speed

Symptom

No link on either Ethernet port, or ETH/G negotiates 100 Mbps instead of 1 Gbps.

Cause

The cable is plugged into the wrong port, the cable is not Cat 5e or higher, or the upstream switch port is hard-set to 100 Mbps.

Fix

  1. Confirm the device is in the correct port: ETH/G is the 1 Gbps port, ETH is the 100 Mbps port.
  2. Use a Cat 5e or Cat 6 cable for Gigabit operation.
  3. Set the upstream switch port to auto-negotiate.
  4. Verify the link with ip -s link show eth0 and ethtool eth0.
The GPIO Add-on port is not Ethernet

The RJ45 socket labeled GPIO is for ALPON Add-on modules only. Connecting an Ethernet cable or a PoE injector to this port causes permanent hardware damage.

Connectivity

Wi-Fi does not see any 5 GHz networks

Symptom

A scan returns 2.4 GHz networks only. The 5 GHz SSID is visible from a phone in the same location.

Cause

The Wi-Fi country code is unset or set to a region that disables the 5 GHz band, so DFS channels do not appear in the scan list.

Fix

  1. Set the regulatory domain with sudo raspi-config under Localisation Options.
  2. Or apply it directly with sudo iw reg set <COUNTRY_CODE> (for example US, GB, DE, TR).
  3. Verify with sudo iw dev wlan0 scan | grep -E "freq|SSID" that 5 GHz frequencies now appear.
  4. Reboot to make the country code persist across firmware reloads.
Connectivity

Network failover does not switch when the primary path drops

Symptom

Ethernet is unplugged or Wi-Fi drops, but the device does not migrate to LTE within the expected window.

Cause

The failover priority list in ALPON Cloud is misconfigured, or the LTE link is in a bad state and the agent has not marked it as a viable backup.

Fix

  1. Open the device in ALPON Cloud and review the network manager priority order: typically ETH/G > ETH > Wi-Fi > LTE.
  2. Confirm the cellular path is healthy with mmcli -m 0 and that an APN is configured.
  3. If failover does not recover connectivity, capture journalctl -u sixfab-connect -n 200 for support. Recovery time depends on the available uplinks and configuration.
GPIO

GPIO Add-on port has no 5 V output

Symptom

An attached Add-on module does not power up. Pin 8 (5 V OUT) reads 0 V.

Cause

The 5 V rail on the GPIO Add-on port is gated by GPIO 21 (ADDON_PWS_EN). On boot it is inactive by default and must be driven HIGH from software.

Fix

Drive GPIO 21 HIGH before initiating any communication with the Add-on module.

enable_addon.py python 
# Enable the GPIO Add-on 5 V rail and check for fault
import RPi.GPIO as GPIO

GPIO.setmode(GPIO.BCM)
GPIO.setup(21, GPIO.OUT)   # ADDON_PWS_EN
GPIO.setup(20, GPIO.IN)    # ADDON_PWS_FAULT

GPIO.output(21, GPIO.HIGH) # Enable the rail

if GPIO.input(20) == GPIO.LOW:
    print("Fault: overcurrent, overtemperature, or reverse voltage")
else:
    print("Add-on rail enabled, 5 V available on Pin 8")
Fault auto-recovery

If overcurrent, overtemperature, or reverse voltage is detected, the port enters protection mode. GPIO 20 (ADDON_PWS_FAULT) reads LOW while the fault persists and returns HIGH once the condition clears.

USB

USB peripherals power off and stay off

Symptom

USB devices on the side ports were enumerated, then power was suddenly cut to both ports simultaneously.

Cause

Combined draw exceeded the 1 A total budget shared by the two USB 2.0 ports. Over-current protection cuts both rails together. There is no software command to re-enable them at runtime.

Fix

  1. Disconnect both USB peripherals.
  2. Perform a full power cycle of the ALPON X4 to restore the USB rails.
  3. For peripherals drawing more than 500 mA, attach a powered USB hub instead of plugging directly into the device.
USB-C is sink-only

The USB-C port on the ALPON X4 is sink-only (power in). It does not provide USB data or power output during normal operation. Use the two USB 2.0 Type-A ports on the side of the device for peripherals.

Hardware

Nothing appears on HDMI

Cause

The HDMI display was connected after boot, the cable does not support the negotiated mode, the Raspberry Pi CM4 has not completed early boot, or the device is in Restricted Mode (HDMI is disabled while input voltage is below 12 V).

Fix

  1. Plug HDMI before powering on. Hot-plug detection is best-effort on the Raspberry Pi CM4.
  2. Use a certified HDMI cable and a monitor that supports 1080p at 60 Hz.
  3. Verify a 12–30 V DC input or the supported 15 V / 1.8 A USB-C PD supply is present for full peripheral functionality.
  4. If the monitor stays blank, verify over SSH that the device booted, then reboot with HDMI already connected.
OS

I cannot SSH into the device

Cause

mDNS may not resolve the .local hostname, the workstation may be on a different VLAN, port 22 may be blocked, or the OS may not have completed booting. Restricted peripheral mode alone does not establish why SSH is unavailable.

Fix

  1. Connect with the correct user. Two reliable ways to reach the device:
terminal shell 
# Two reliable ways to reach the device
ssh alpon@alpon-<MAC>.local      # mDNS, requires same VLAN
ssh alpon@<DEVICE_IP>           # Direct, works across routed subnets

# Default password: sixfab, change before production
sudo passwd alpon
  1. On Windows hosts install Bonjour or use a recent Windows 10/11 build. mDNS is link-local and does not cross routers.
  2. If the local network is unreachable, use the browser-based remote terminal in ALPON Cloud. It works even when only cellular is up.
  3. As a last resort, attach HDMI and a USB keyboard for local login.
OS

I forgot the password I set for the alpon user

Cause

The alpon account password was changed and lost. The default sixfab password no longer works.

Fix

  1. If you retain authorized remote terminal access in ALPON Cloud, open that terminal.
  2. From an authorized shell with sudo privileges, set a new password: sudo passwd alpon. If sudo requires the lost password, use the support recovery path below.
  3. If no remote access is available, contact Sixfab support with the device serial number for a recovery procedure.
Do not delete the alpon user

The alpon account is used by ALPON Cloud and other system services. Keep it intact and create an additional admin user with sudo rights if needed. See the OS guide before changing service accounts.

OS

apt update or apt upgrade fails

Symptom

sudo apt update reports unreachable repositories, GPG signature errors, or hash sum mismatches.

Cause

No network path is up, the system clock is wildly wrong (TLS validation fails), or a previous transaction was interrupted and the dpkg state is dirty.

Fix

terminal shell 
# Confirm an uplink first
ping -c 3 1.1.1.1

# Verify the system clock is current
timedatectl
sudo timedatectl set-ntp true

# Repair any half-configured packages
sudo dpkg --configure -a
sudo apt -f install

# Refresh and retry
sudo apt update
sudo apt upgrade -y

Reboot if a kernel or firmware package was upgraded.

Stagger fleet rollouts

For production fleets, push apt upgrade one device at a time through ALPON Cloud and monitor the Connection LED before moving to the next. This isolates regressions caused by upstream package changes.

Hardware

RTC time drifts after a power cycle

Symptom

The system clock jumps back several hours or to an old date after every power-off, even with a brief outage.

Cause

The RTC battery may be depleted, or time synchronization may not be working. Battery condition requires service diagnosis; clock drift alone is not proof of battery failure.

Fix

  1. As a stopgap, ensure NTP is enabled: sudo timedatectl set-ntp true. The clock will resync once the device reaches the network.
  2. Contact Sixfab support for RTC diagnosis and authorized battery service. Do not open the enclosure or replace the battery yourself.
ALPON Cloud

Device shows as offline in ALPON Cloud

Symptom

The device is powered on but the asset list in ALPON Cloud shows it as offline. The Connection LED is off.

Cause

The sixfab-connect agent cannot reach the cloud, the device has not been activated for the workspace, or no network path has a working uplink.

Fix

  1. Check the LED reference above. If the Cellular LED is red, fall back to Ethernet by plugging ETH/G into a wired router.
  2. From a local shell, inspect the agent:
    terminal shell 
    systemctl status sixfab-connect
journalctl -u sixfab-connect -n 200 --no-pager
  3. If the agent is stuck, restart it:
    terminal shell 
    sudo systemctl restart sixfab-connect
  4. In ALPON Cloud, confirm the device is activated via the Active/Inactive toggle on the asset detail page.
  5. Verify at least one path (LTE, Wi-Fi, or Ethernet) has a healthy upstream route.
ALPON Cloud

Container fails to start with exec format error

Symptom

docker run fails with exec format error, or a container deployed from ALPON Cloud is reported as crashed.

Cause

The image is built for amd64 (x86_64) instead of ARM64. The Raspberry Pi CM4 is ARMv8 and only runs linux/arm64 binaries.

Fix

  1. On a workstation, cross-build for the right platform: docker buildx build --platform linux/arm64 -t myimage:latest --push .
  2. Or build natively on the ALPON X4 with docker build ..
  3. Verify the image architecture before deploy: docker inspect <image> | grep Architecture.
  4. Re-deploy through ALPON Cloud after pushing the corrected image.
ALPON Cloud

An application update is stuck or the expected version is not running

Symptom

An OTA update reports in progress for an extended period, or the device reports the previous version after the rollout completes.

Cause

Possible causes include insufficient eMMC space, an interrupted download, or failure to start the new container. Inspect the deployment status and logs rather than assuming an automatic rollback occurred.

Fix

  1. Check available eMMC space with df -h / and compare it with the image's requirements. Review unused images before removing any; retain versions needed for recovery.
  2. Confirm the active link is stable. If the OTA started on LTE, switch to Ethernet and retry.
  3. Inspect the agent log: journalctl -u sixfab-connect -n 300 --no-pager.
  4. If the new image fails to start, diagnose the container logs, correct the application, and redeploy through the supported ALPON Cloud workflow.
ALPON Cloud

The QR code on the label does not scan

Fix

  1. In ALPON Cloud, choose Manual registration.
  2. Enter the serial number printed next to the QR code.
  3. Follow the on-screen prompts to bind the device to your organization.

Before you contact support

Record these seven checks to help isolate the issue and provide useful context to support. The chip on the right of each row tells you what to do — $ means a shell command to run, → means a visual or label to confirm.

01
Power source $vcgencmd get_throttled

Use one supported source: 15 V / 1.8 A (27 W) USB-C PD, 12–30 V DC for full function, or optional PoE+ within its 25 W delivered budget. Record any under-voltage flags.

02
Switch positions →SW1 · SW2 · OFF

SW1 (Watchdog) and SW2 (Boot/Burn) both OFF for normal operation. Toggle only with all power disconnected.

03
LED state →PWR · CONN · CELL

Note the exact state of Power, Connection, and Cellular LEDs. See the LED reference.

04
Antennas seated →L · L · G · W

Check antennas with power disconnected. LTE Main, LTE Diversity, and GNSS/GPS use SMA; Wi-Fi/Bluetooth uses RP-SMA. Match each antenna to its labeled port.

05
Network path $ping -c 3 1.1.1.1

At least one of LTE, Wi-Fi, ETH/G, or ETH reaches the internet.

06
Cloud agent $systemctl status sixfab-connect

The sixfab-connect service reports as active (running).

07
Device serial number →SN-XXXXXXXX

Read it from the enclosure label, next to the QR code. Include it in the support ticket.

Optional: collect a support bundle

If you can run a shell on the device (SSH or HDMI), this single block captures the journal, kernel ring buffer, power state, modem status, and OS release into one archive. Attach it to your ticket if you can; otherwise the checks above are enough to start.

terminal (on the ALPON X4) shell 
# Single-shot bundle, run on the device over SSH
sudo journalctl -b -n 2000 > ~/alpon-x4-journal.log
dmesg > ~/alpon-x4-dmesg.log
vcgencmd get_throttled > ~/alpon-x4-power.log
mmcli -m 0 > ~/alpon-x4-modem.log
cat /etc/os-release > ~/alpon-x4-os.log
tar czf ~/alpon-x4-support.tar.gz ~/alpon-x4-*.log
# Copy the archive to your computer with scp, WinSCP, or Cyberduck.
No shell access?

Send a plain-text email with the device serial number, the observed LED state, and a one-line description of what you were doing when the issue appeared. Sixfab support can guide you through log collection from there.

Still need help?

If your symptom is not covered above, contact Sixfab support. Include the checks above or the support bundle, along with the device serial number and observed behavior.

Sixfab support

Couldn't fix it with the cards above?

Attach the support bundle (~/alpon-x4-support.tar.gz) along with the observed LED state and the device serial number. Review logs for credentials and personal data before sharing them through the support channel.

Open a support ticket One-on-one with the Sixfab team. Best for blocking issues. Ask the community Browse threads or post a question on the Sixfab forum.

Related guides

ALPON X4 Quickstart
Check the supported setup and registration workflow.
Physical Layout & I/O
Identify ports, switches, LEDs, and GPIO connections.
FAQ
Find answers about hardware, power, and ALPON Cloud.

Updated about 1 hour ago

Did this page help you?