# Known Issues

This page documents known issues, limitations, and workarounds for the AddVantage PPG firmware and test tools.

## Firmware Issues

### WDOG-001: Watchdog Must Be Disabled Immediately

**Severity:** Critical

**Description:**
The SKEAZ128 watchdog timer must be disabled within 256 bus clock cycles after reset. If any code executes before the watchdog unlock sequence, the device will boot loop.

**Symptoms:**
- Device continuously resets
- Multiple version strings in UART output
- "Boot loop detected" in test harness

**Root Cause:**
The default ARM startup code (`__thumb_startup` from EWL) performs C runtime initialization before calling `main()`. This takes longer than the watchdog timeout window.

**Solution:**
A custom reset handler in `startup_wdog.S` disables the watchdog immediately:

```text
Reset_Handler:
    ldr r0, =0x40052000   ; WDOG base
    ldr r1, =0x20C5       ; Unlock key 1
    ldr r2, =0x28D9       ; Unlock key 2
    strh r1, [r0, #0x0E]  ; Write to WDOG_UNLOCK
    strh r2, [r0, #0x0E]  ; Complete unlock
    movs r1, #0x00
    strh r1, [r0, #0x00]  ; Disable WDOG via WDOG_CS1
```

**Status:** Fixed in v3.2.7

---

### CAN-001: Oil Temperature Not Reliable from Simulator

**Severity:** Low

**Description:**
The oil temperature field (from PGN ET1 bytes 2-3) occasionally reads -40°C or other incorrect values when using the CAN simulator test box.

**Symptoms:**
- Oil temp shows -40°C or fluctuates wildly
- Only occurs with test equipment, not live engines

**Root Cause:**
The CAN simulator test box does not correctly simulate the 16-bit oil temperature field in the ET1 message. The coolant temperature (byte 0) works correctly.

**Workaround:**
The firmware uses coolant temperature for all thermal logic, so this does not affect operation. The CAN viewer and validation tools ignore oil temperature.

**Status:** Known limitation of test equipment (not a firmware bug)

---

### FLASH-001: Limited Erase Cycles

**Severity:** Low

**Description:**
Flash memory has approximately 10,000 erase cycles per sector. Frequent configuration changes could wear out the flash.

**Symptoms:**
- Configuration fails to save
- Values revert after power cycle

**Workaround:**
- Avoid frequent configuration changes
- Batch changes and save once
- For development, consider external EEPROM

**Status:** Hardware limitation

---

## Test Harness Issues

### TH-001: J-Link GUI Picker Interrupts Automation

**Severity:** Medium

**Description:**
When multiple J-Links are connected, the J-Link software shows a GUI picker dialog, blocking automation scripts.

**Symptoms:**
- Test script hangs waiting for user input
- "No response from J-Link" errors in CI

**Workaround:**
The flash script specifies a fixed J-Link serial number:

```python
# In tools/flash.py
JLINK_SERIAL = "50114603"
```

Update this value to match your J-Link's serial number.

**Status:** Workaround implemented

---

### TH-002: Serial Port Auto-Detection May Choose Wrong Port

**Severity:** Low

**Description:**
On systems with multiple USB-serial adapters, the auto-detection may choose the wrong port.

**Symptoms:**
- "No output received" when correct hardware is connected
- Data from wrong device

**Workaround:**
Explicitly specify the port:

```bash
python tools/test_harness.py --hex build/addvantage3.hex --port /dev/cu.usbmodem55014603
```

**Status:** Won't fix (by design - auto-detect is a convenience feature)

---

### TH-003: PCAN Library Path on macOS

**Severity:** Medium

**Description:**
The PCAN library (libPCBUSB.dylib) must be in `~/lib` on macOS. If not found, CAN validation fails.

**Symptoms:**
- "CAN validation: python-can or PCAN library not available"
- Import errors when running can_capture.py

**Workaround:**
Copy the library to the expected location:

```bash
mkdir -p ~/lib
cp /path/to/libPCBUSB.dylib ~/lib/
```

The tools set `DYLD_LIBRARY_PATH` automatically.

**Status:** Documented

---

## Build Issues

### BUILD-001: CodeWarrior Legacy Build Deprecated

**Severity:** Info

**Description:**
The original CodeWarrior build system is deprecated. Use the CMake build instead.

**Symptoms:**
- Make errors in DEBUG directory
- Missing ProcessorExpert files

**Solution:**
Use CMake build:

```bash
mkdir build && cd build
cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../arm-gcc-toolchain.cmake ..
ninja
```

**Status:** CMake build is the supported method

---

### BUILD-002: ARM Toolchain Version Sensitivity

**Severity:** Low

**Description:**
Some older ARM GCC versions produce different code sizes or may have bugs in Cortex-M0+ codegen.

**Symptoms:**
- Warning messages during compilation
- Slightly different binary output

**Workaround:**
Use ARM GCC 10.3 or newer. The official ARM download is recommended over distro packages.

**Status:** Documented

---

## Documentation Issues

### DOC-001: Some C Functions Lack Doxygen Comments

**Severity:** Low

**Description:**
Not all C functions have Doxygen-style documentation comments. API reference may be incomplete.

**Affected Files:**
- `Events.c` - Partial coverage
- `can.c` - Minimal comments
- `adc.c` - Minimal comments

**Status:** Documentation improvement in progress

---

## Reporting New Issues

To report a new issue:

1. Check this page for existing known issues
2. Reproduce the issue with latest firmware
3. Collect relevant logs (UART output, test harness output)
4. Open an issue at: https://github.com/[repo]/issues

Include:
- Firmware version
- Hardware configuration
- Steps to reproduce
- Expected vs actual behavior
- Relevant log output