> For the complete documentation index, see [llms.txt](https://amobile-solutions.gitbook.io/yocto-developer-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://amobile-solutions.gitbook.io/yocto-developer-guide/getting-started/iot-800n-g420/faq-and-troubleshooting.md).

# FAQ & Troubleshooting

## The board boots part way and stops

Three configuration values cause this, and none of them produces a useful error message.

### The kernel starts but never finds a root filesystem

Look at the last lines on the console. `Waiting for root device` or `VFS: Cannot open root device` means the UFS overlay was not applied.

```
KERNEL_DEVICETREE_OVERLAYS_AUTOLOAD:iot800n-g420 += "ufs.dtbo"
```

The SoM boots from UFS, and the UFS controller node is enabled by that overlay. It belongs in `local.conf`.

### The board stops before kernel init

`OPTEE_DRAM_SIZE` set too small puts OP-TEE's secure memory at an address that does not exist. The working value is `0x200000000`.

### An inconsistent kernel

`SRC_URI = ""` and `SRCREV = "INVALID"` must appear before `inherit externalsrc` in the kernel bbappend. Without them, kernel-yocto's patch queue still sees the MediaTek patch entries and applies them on top of a tree where they are already present.

***

## Board revision differences

Carrier revision **R02** changed three things that affect software. Images built for R0.1 will not work correctly on R02 and vice versa.

### I2C0 has no external pull-ups on R02

R0.1 had 2.2K pull-ups to VIO18\_PMU on the sensor bus, so the device tree used `bias-disable`. R02 marks all of them NM, which leaves SDA and SCL floating.

The symptom is `bmi270_i2c` failing with `-ETIMEDOUT`, and `i2cdetect` aborting partway through the scan rather than reporting no devices — a dead bus looks like a missing part.

The fix is `bias-pull-up` on `i2c0_pins`.

### NFC power moved from GPIO3 to GPIO4

On R0.1 a single GPIO did both jobs. R02 removed the MC3416 accelerometer, which freed GPIO4, and split them:

| GPIO | Function                                               |
| ---- | ------------------------------------------------------ |
| 4    | Enables the SGM66055 boost converter producing PTX\_5V |
| 3    | The PTX130R's own SEN pin                              |

Power has to come up before SEN is asserted. Without the new rail the chip is unpowered and SPI reads back `0xFF` for every byte, which looks like a bus fault rather than a missing supply.

{% hint style="info" %}
The schematic net for GPIO4 is still named `GPIO4_GSENSOR_INT` even though it no longer has anything to do with the accelerometer.
{% endhint %}

### The speaker amplifier changed on R02

R0.1 used an AW87390, which had I2C control. R02 uses a PT3300, which has none: its gain is fixed by resistors and its input comes straight from the PMIC's HP-R output.

`CONFIG_SND_SOC_AW87XXX` is therefore disabled and the device tree node removed. Audio is unaffected — neither part was ever an ASoC codec, so nothing in the audio path depended on the driver.

The PT3300's shutdown pin is on `GPIO58`, held high by the board, so the amplifier is enabled from power-on. Driving that line low mutes the speaker while leaving the line output active.

***

## The display shows a test pattern instead of the image

The panel's TCON has entered its built-in self test. It does that when it receives LVDS video before it is ready, and it does not leave that state without a full power cycle.

Table 18 of the panel specification gives two timings after SLPOUT goes high: `T_LOAD1` at 20 ms minimum and `T_LOAD2` at 50 ms minimum, during which the panel loads its parameters from internal flash and stays in Black Frame Mode.

The panel driver must therefore wait at least 70 ms after SLPOUT before returning. The shipped driver waits 100 ms.

***

## The DB9 serial port does nothing

The port runs through an F81439AN multi-protocol transceiver whose mode is selected by three GPIO lines. With nothing holding them, the pull-ups select **low power shutdown** — every I/O pin high impedance.

```
am-serial-mode              show the current mode
am-serial-mode list         every mode and its DB9 pinout
am-serial-mode rs232
am-serial-mode test         loopback, with pin2 shorted to pin3
```

The `am-serial-mode` service applies `SERIAL_MODE` from `/etc/amobile/serial.conf` at boot, defaulting to RS-232.

{% hint style="warning" %}
libgpiod releases a line when the process holding it exits, so the mode only lasts while something holds those three lines. The service keeps a process alive for exactly this reason.
{% endhint %}

***

## Serial, CAN and LTE all disappear together

Those three sit behind the internal GL852G USB hub, whose power comes from a GPIO-controlled rail. If that rail is not enabled the hub is unpowered and everything behind it vanishes at once.

The two USB Type-A ports come straight from the SoC and keep working, which makes the symptom look stranger than it is.

***

## WiFi does not appear

The MT7921 needs the PMIC's `vcn18` rail, which supplies the IO side of the SDIO bus. Without it the chip never answers CMD5 and mmc2 reports `error -110`.

```
grep vcn18 /sys/kernel/debug/regulator/regulator_summary
```

A `use_count` of 0 means the rail is not enabled. Unbinding and rebinding the driver does not help — rebinding does not make a missing supply appear.

***

## The camera image has wrong colours

The Bayer order is GRBG. It cannot be derived reliably from photographs of real scenes, because in low-saturation images the four channels differ by only a few percent and noise flips the result.

Use the sensor's built-in colour bars instead:

```
v4l2-ctl -d /dev/v4l-subdev1 -c test_pattern=2
```

The bars must read white, yellow, cyan, green, magenta, red, blue, black.

```
v4l2-ctl -d /dev/v4l-subdev1 -c test_pattern=0
```

***

## GNSS reports no satellites

Indoors this is expected. The receiver needs the antenna to see the sky, and a cold start takes 30 seconds to 2 minutes outdoors.

To confirm the software path is working without a fix:

```
gps-info.sh fw          firmware version, read back from the chip
gpspipe -r -n 20        raw NMEA sentences
```

Reading the firmware version back is the strongest single check: it proves SPI communication, the bootloader and the main firmware are all working.

***

## CAN receives but does not transmit

`TX packets 0` with `errors 0` and `dropped 1` means frames are being discarded before they reach the controller.

Check `dmesg` for:

```
f81604_read_int_callback: short int URB: 9 < 12
```

That indicates the mainline `f81604` driver and this chip's firmware disagree about the interrupt packet format. The vendor driver from Fintek uses a different expected length and is required for transmit to work.

***

## libgpiod version differences

The image ships libgpiod **v2**, whose command syntax differs from v1 in ways that fail silently in scripts.

|              | v1                                          | v2                                         |
| ------------ | ------------------------------------------- | ------------------------------------------ |
| Read a line  | `gpioget gpiochip0 3`                       | `gpioget -c gpiochip0 3` or by name        |
| Set a line   | `gpioset gpiochip0 3=1` returns immediately | `gpioset NFC_SEN=1` blocks while holding   |
| Find by name | `gpiofind NAME`                             | names work directly in `gpioget`/`gpioset` |

{% hint style="warning" %}
`--banner` only exists from v2.2. On v2.1 the command fails outright, and if stderr is redirected the failure is invisible while the line is never driven.
{% endhint %}

***

## Where to look next

Detailed hardware documentation ships with the SDK:

```
src/meta-amobile-iot800n-g420/docs/
    HW-MAP.md              schematic to software mapping, GPIO tables
    DRIVER-PORTING.md      out-of-tree drivers and API differences
    GPIO-USER-GUIDE.md     digital IO and serial mode pins
    OPEN-QUESTIONS.md      unresolved items and findings worth keeping
```