# RP2350 TFT Display with Touch and SD Card Demo

A modular embedded application for RP2350 microcontrollers featuring display, touch, and SD card support with hardware abstraction layers.

## Features

- **Display Abstraction Layer** - Support for multiple display types (ST7796, ST7789, E-Paper)
- **Touch Abstraction Layer** - Extensible touch controller support (FT6336U)
- **SD Card with FatFS** - File system support with board-aware initialization
- **Multi-Board Support** - Automatic pin configuration for different RP2350 boards
- **1-bit Rendering** - Memory-efficient monochrome graphics with GUI widgets
- **Board Configuration** - Single configuration file for all hardware settings

## Supported Hardware

### Boards
1. **Adafruit Feather RP2350** (default)
2. **Raspberry Pi Pico 2**
3. **Raspberry Pi Pico 2 W**

### Displays
- ST7796 (480x320 TFT LCD) - Fully implemented
- ST7789 - Ready for driver implementation
- E-Paper - Ready for driver implementation

### Touch Controllers
- FT6336U (I2C capacitive touch) - Fully implemented
- Extensible for additional controllers

### Storage
- SD Card via SPI with FatFS file system

## Quick Start

### Building for Default Board (Feather RP2350)

```bash
mkdir -p build
cd build
cmake -G Ninja ..
ninja
```

### Building for Specific Board

```bash
cmake -G Ninja -DPICO_BOARD=pico2 ..
ninja
```

Available boards: `adafruit_feather_rp2350`, `pico2`, `pico2_w`

### Building for All Boards

```bash
./build_all_boards.sh
```

Generates:
- `basic1_adafruit_feather_rp2350.uf2`
- `basic1_pico2.uf2`
- `basic1_pico2_w.uf2`

### Flashing

1. Hold BOOTSEL button while connecting USB
2. Copy the `.uf2` file to the mounted drive
3. Device will automatically reboot and run

Or use the flash script:
```bash
./build_and_flash.sh
```

## Project Structure

```
basic1/
├── basic1.cpp                      # Main application
├── board_config.h                  # Board-specific pin configuration
├── CMakeLists.txt                  # Build configuration
├── build_all_boards.sh             # Multi-board build script
├── build_and_flash.sh              # Build and flash helper
│
├── display/                        # Display and GUI abstraction
│   ├── low_level_display.h         # Display interface
│   ├── low_level_display_*.cpp     # Display implementations
│   ├── low_level_touch.h           # Touch interface
│   ├── low_level_touch_*.cpp       # Touch implementations
│   ├── low_level_render.h/cpp      # 1-bit rendering engine
│   └── low_level_gui.h/cpp         # GUI widgets
│
├── lib/                            # Hardware drivers
│   ├── ft6336u/                    # FT6336U touch driver
│   ├── st7796/                     # ST7796 display driver
│   ├── sd_card/                    # SD card driver with FatFS test
│   └── fatfs/                      # FatFS filesystem
│
├── fonts/                          # Bitmap font definitions
└── fatfs_time.c                    # FatFS timestamp (uses compile time)
```

## Configuration

### Board Configuration (`board_config.h`)

All hardware settings are defined per board:

```c
// Display configuration
#define DISPLAY_WIDTH 480
#define DISPLAY_HEIGHT 320
#define DISPLAY_TYPE_SELECTED 0  // DISPLAY_TYPE_ST7796

// Touch configuration
#define TOUCH_TYPE_SELECTED 0  // TOUCH_TYPE_FT6336U
#define TOUCH_SWAP_XY true
#define TOUCH_INVERT_X true
#define TOUCH_INVERT_Y false

// SPI pins for display
#define DISPLAY_SPI_PORT spi1
#define DISPLAY_SCK_PIN  18
#define DISPLAY_MOSI_PIN 19
#define DISPLAY_MISO_PIN 20
#define DISPLAY_CS_PIN   17
// ... more pins
```

### Changing Display Type

Modify `DISPLAY_TYPE_SELECTED` in `board_config.h`:
- `0` = ST7796 (480x320 TFT)
- `1` = ST7789
- `2` = E-Paper

### Changing Touch Type

Modify `TOUCH_TYPE_SELECTED` in `board_config.h`:
- `0` = FT6336U
- `1` = None (disable touch)

### Touch Coordinate Transformation

Adjust orientation in `board_config.h`:
```c
#define TOUCH_SWAP_XY true      // Swap X/Y coordinates
#define TOUCH_INVERT_X true     // Invert X axis
#define TOUCH_INVERT_Y false    // Invert Y axis
```

## Architecture

### Display Abstraction Layer

Provides a unified interface for different display types:

```cpp
class LowLevelDisplay {
public:
    virtual bool init() = 0;
    virtual void clear(bool white = true) = 0;
    virtual void draw_buffer(const uint8_t* bit_buffer) = 0;
    virtual void refresh() = 0;
    // ... more methods
    
    static LowLevelDisplay* create(DisplayType type, int width, int height);
};
```

Usage:
```cpp
LowLevelDisplay* display = LowLevelDisplay::create(
    (DisplayType)DISPLAY_TYPE_SELECTED, V_WIDTH, V_HEIGHT);
display->init();
display->draw_buffer(buffer);
display->refresh();
```

### Touch Abstraction Layer

Unified interface for touch controllers:

```cpp
class LowLevelTouch {
public:
    virtual bool init() = 0;
    virtual bool read_touch(TouchData* data) = 0;
    virtual bool is_touched() = 0;
    // ... more methods
    
    static LowLevelTouch* create(TouchType type, int width, int height,
                                 bool swap_xy, bool invert_x, bool invert_y);
};
```

Usage:
```cpp
LowLevelTouch* touch = LowLevelTouch::create(
    (TouchType)TOUCH_TYPE_SELECTED, V_WIDTH, V_HEIGHT,
    TOUCH_SWAP_XY, TOUCH_INVERT_X, TOUCH_INVERT_Y);
    
TouchData touch_data;
if (touch->read_touch(&touch_data)) {
    int x = touch_data.points[0].x;
    int y = touch_data.points[0].y;
    // Handle touch
}
```

### SD Card Abstraction

Board-aware initialization:

```cpp
// Initialize with board configuration
if (sd_card_init_with_board_config()) {
    // Test FatFS functionality
    sd_card_test_fatfs();
}
```

The test function:
- Mounts FatFS
- Lists directory contents
- Creates and reads test file
- Safely unmounts filesystem

## Pin Configurations

### Adafruit Feather RP2350
- **Display (SPI1):** SCK=18, MOSI=19, MISO=20, CS=17, DC=16, RST=15, BL=14
- **Touch (I2C0):** SDA=4, SCL=5, INT=6, RST=7
- **SD Card (SPI1):** CS=10 (shares SPI with display)

### Raspberry Pi Pico 2 / Pico 2 W
- **Display (SPI0):** SCK=2, MOSI=3, MISO=4, CS=5, DC=6, RST=7, BL=8
- **Touch (I2C0):** SDA=12, SCL=13, INT=14, RST=15
- **SD Card (SPI1):** CS=17

## Adding New Hardware

### Adding a New Display Driver

1. Create implementation files:
   ```cpp
   display/low_level_display_mydriver.h
   display/low_level_display_mydriver.cpp
   ```

2. Implement the `LowLevelDisplay` interface

3. Add to factory in `low_level_display_factory.cpp`:
   ```cpp
   case DISPLAY_TYPE_MYDRIVER:
       display = new LowLevelDisplayMyDriver(width, height);
       break;
   ```

4. Update `CMakeLists.txt` to include new files

### Adding a New Touch Controller

1. Create implementation files:
   ```cpp
   display/low_level_touch_mydriver.h
   display/low_level_touch_mydriver.cpp
   ```

2. Implement the `LowLevelTouch` interface

3. Add to factory in `low_level_touch_factory.cpp`

4. Update `CMakeLists.txt`

### Adding a New Board

Edit `board_config.h`:

```c
#elif defined(PICO_BOARD_MY_CUSTOM_BOARD)
    #define BOARD_NAME "My Custom Board"
    
    // Display configuration
    #define DISPLAY_WIDTH 480
    #define DISPLAY_HEIGHT 320
    #define DISPLAY_TYPE_SELECTED 0
    
    // Touch configuration
    #define TOUCH_TYPE_SELECTED 0
    // ... define all pins
#endif
```

## Memory Usage

- **1-bit framebuffer:** 480×320÷8 = 19.2 KB
- **Display conversion:** Automatic 1-bit → RGB565/monochrome
- **Stack/heap:** Minimal, uses static buffers where possible

## Known Issues & Troubleshooting

### Touch Not Working
- **I2C Communication Failure:** Check wiring, pull-up resistors, I2C address
- **Wrong Coordinates:** Adjust `TOUCH_SWAP_XY`, `TOUCH_INVERT_X/Y` settings

### SD Card Not Detected
- **CMD0 Returns 0x00:** Check card insertion, CS pin, SPI wiring
- **Mount Fails:** Ensure card is formatted as FAT/FAT32

### Display Shows Nothing
- Check SPI wiring and CS/DC/RST pins
- Verify backlight is connected and enabled
- Check voltage levels (3.3V logic)

## Features by Component

### Display Features
- 1-bit monochrome rendering
- RGB565 color support (ST7796)
- Drawing primitives (lines, rectangles, circles)
- GUI widgets (windows, gauges, status bars)
- Multiple font support

### Touch Features
- Multi-touch support (up to 2 points)
- Coordinate transformation
- Touch debouncing
- Event types (press, lift, contact)

### SD Card Features
- SPI mode support
- FatFS integration
- Directory listing
- File read/write
- Automatic timestamps from compile time

## License

Copyright (c) 2021 Arm Limited and Contributors. All rights reserved.
SPDX-License-Identifier: Apache-2.0

## Dependencies

- Raspberry Pi Pico SDK 2.2.0+
- FatFS (included)
- TinyUSB (via SDK)
- Hardware drivers (included in `lib/`)

## Contributing

When adding new features:
1. Follow the abstraction layer pattern
2. Update `board_config.h` for hardware settings
3. Keep application code hardware-agnostic
4. Test on multiple boards if possible
5. Update this README