Troubleshooting¶

Common issues and how to fix them.

Installation Issues¶

"Docker not found"¶

Symptoms: embsec init fails with Docker error

Fix: 1. Install Docker Desktop (Windows/Mac) or Docker Engine (Linux) 2. Start Docker 3. Run docker --version to verify

"Permission denied"¶

Symptoms: Docker commands fail with permission errors

Fix for Linux:

sudo usermod -aG docker $USER
newgrp docker  # or log out and back in

Fix for Windows: Run terminal as Administrator

Container Issues¶

"embsec up" fails¶

Symptom: Container won't start

Checks:

# Is Docker running?
docker ps

# Any existing containers?
docker ps -a | grep embsec

# Remove old container
docker rm -f embsec-dev

VS Code won't open¶

Symptom: Browser doesn't open or shows error

Fixes: 1. Try manually opening: http://localhost:8443 2. Check if port is in use:

embsec down
embsec config set vscode.port 8444
embsec up

Container runs slowly¶

Symptom: Everything is sluggish

Fixes: 1. Allocate more resources in Docker Desktop settings 2. Close other applications 3. On Windows: Ensure files are in WSL2 filesystem, not Windows

USB/TM4C123G Issues¶

Board not detected¶

Symptom: lm4flash can't find device

Checks:

# Is board connected?
lsusb | grep Texas

# Try different USB port
# Use USB 2.0 port if available

# Reset board
# Hold RESET button while connecting USB

Platform-specific:

# Check permissions
ls -l /dev/ttyACM*

# Add to dialout group
sudo usermod -aG dialout $USER
# Log out and back in

# In PowerShell as Admin
usbipd wsl list
usbipd wsl attach --busid X-X

"Failed to halt target"¶

Symptom: Can't flash program

Fixes: 1. Hold SW1 while running lm4flash 2. Try: lm4flash -r program.bin (reset first) 3. Unplug and replug board 4. Check if program is stuck in infinite loop

Serial output not working¶

Symptom: UART/printf not showing

Fix:

# Check device exists
ls /dev/ttyACM*

# Correct screen command
screen /dev/ttyACM0 115200

# Exit screen: Ctrl+A, K, Y

Build Issues¶

"arm-none-eabi-gcc: command not found"¶

Symptom: Can't compile

Fix: You're not in the container. Run embsec up first.

Compilation errors¶

Common fixes: 1. Check include paths in Makefile 2. Verify TivaWare library path: /workspace/driverlib 3. Use correct MCU flags: -mcpu=cortex-m4

"undefined reference" errors¶

Fix: Link against driver library:

-L/workspace/driverlib -ldriver

Quick Fixes¶

Reset everything¶

embsec down --purge
embsec init --force
embsec up

Check system health¶

embsec doctor
embsec doctor --fix  # Try auto-fix

View detailed logs¶

embsec logs --tail 50
embsec logs --follow  # Live logs

Getting More Help¶

1. Run embsec doctor for automated diagnostics
2. Check container logs: embsec logs
3. Ask in class Discord/forum
4. Include error messages when asking for help

Platform-Specific Notes¶

Windows/WSL2¶

• Keep project files in WSL filesystem (/home/username/)
• Not in Windows paths (/mnt/c/)
• Use Windows Terminal for better experience

macOS Apple Silicon¶

• Docker Desktop handles architecture translation
• Some tools may run slower due to emulation

Linux¶

• Native performance
• May need to configure udev rules for some boards