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, the most likely cause, and the verified fix.

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 / 27 W USB-C PD, DC 9 V to 30 V, or PoE+ on PoE-variant SKUs), 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

Most "dead on arrival" reports resolve with a 15 V / 27 W USB-C PD adapter or a 9 V to 30 V DC supply on the terminal block. Standard 5 V phone chargers do not negotiate enough voltage to boot the Raspberry Pi CM4. Start every diagnostic here.

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 rails are stable. Lights about 3 seconds after a valid input is connected.
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 Cannot reach ALPON Cloud. Check the LTE antennas, move the device for better RF, or connect ETH/G to an upstream router. First boot can take up to 3 minutes.
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 happens, and the verified fix. 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

Nothing lights up within 3 seconds of connecting power. The Power LED stays off.

Cause

The USB-C adapter does not negotiate 15 V / 27 W. Standard USB-C phone chargers deliver 5 V only and the ALPON X4 will not boot.

Fix

  1. Use the 27 W USB-C PD adapter shipped with the device.
  2. If unavailable, wire the DC terminal block to a 9 V to 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

The ALPON X4 has entered Restricted Mode. Input voltage has dropped below 12 V, so the peripheral rails are disabled by design while the Raspberry Pi CM4, LTE modem, and both Ethernet ports stay alive.

Fix

  1. Replace any 5 V source with a 15 V USB-C PD adapter or a 9 V to 30 V DC supply on the terminal block.
  2. For long DC cable runs, prefer a 24 V adapter with thicker conductors to compensate for voltage drop.
  3. Reboot after restoring nominal voltage so the peripheral rails re-enable.
Restricted Mode is by design

Restricted Mode prevents brownouts at low input voltage. The Raspberry Pi CM4, LTE modem, and both Ethernet ports stay alive so the device remains reachable for remote diagnostics; USB 2.0 ports, the GPIO Add-on 5 V rail, HDMI output, and the Programmable RGB LED are disabled until nominal voltage is restored.

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 adapter delivers the minimum 27 W but cannot hold it under combined LTE transmission, USB peripherals, and GPIO 5 V draw. Or the enclosure is mounted so airflow across the aluminum heatsink is blocked.

Fix

  1. Switch to an adapter with headroom above 27 W when running the LTE radio at peak transmit alongside USB peripherals.
  2. Mount the device with the cooling surface facing up and leave at least 25 mm clearance in enclosed cabinets.
  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. Move SW1 back to OFF once your application is actively petting the watchdog.
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. Verify the injector reports a Class 4 powered device on its diagnostic LED.
  4. If the SKU does not include PoE, fall back to USB-C PD or the DC terminal block.
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. Hand-tighten both antennas on the SMA connectors labeled L (LTE Main and LTE Diversity). Never connect the Wi-Fi antenna (RP-SMA male) to an LTE port.
  2. Reposition the device away from metal panels and dense walls. The fanless aluminum enclosure is RF-transparent on the antenna side only.
  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. If using a third-party SIM, insert it into the nano-SIM slot and select that profile in ALPON Cloud.
  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. Recovery typically completes in under one minute. If failover takes longer, capture journalctl -u sixfab-connect -n 200 for support.
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 input voltage is at least 12 V DC or 15 V USB-C PD so the device leaves Restricted Mode.
  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 is not resolving the .local hostname, the workstation is not on the same VLAN as the device, the firewall is blocking port 22, or the device is in Restricted Mode and never finished booting.

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. Open the browser-based remote terminal in ALPON Cloud. It authenticates through the cloud agent and bypasses the local password.
  2. From that shell, set a new password: sudo passwd alpon.
  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 internally by the Sixfab Connect agent and other system services. Deleting it breaks remote terminal access, OTA updates, and the network failover manager. Create an additional admin user with sudo rights and keep alpon intact.

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 CR1220 coin cell backing the real-time clock is depleted. Designed lifetime is up to 10 years.

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. Replace the CR1220 battery. Contact Sixfab support for the replacement procedure if the device is still under warranty.
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

OTA update is stuck or rolls back

Symptom

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

Cause

The eMMC is short on free space, the link is dropping during the download, or the new container failed its health check and the agent rolled back automatically.

Fix

  1. Free space on eMMC: df -h / should show at least 500 MB free. Prune old container images with docker image prune -a.
  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 its health probe, fix the container and re-publish a new revision in ALPON Cloud.
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

Seven quick checks that resolve more than 90 % of field issues. Each takes under a minute. 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

15 V / 27 W USB-C PD or 9 V to 30 V DC. No under-voltage flag set.

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

Four SMA connectors hand-tight. LTE Main, LTE Diversity, GNSS/GPS = SMA female; Wi-Fi/Bluetooth = RP-SMA male.

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. Including the seven checks from the section above (or the support bundle) in your ticket turns a multi-day debugging cycle into a single round-trip.

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. Typical first response in one business day.

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.

Updated 16 days ago