# Board Support

This page provides a comprehensive and up-to-date list of all microcontroller boards and platforms supported by `jescore`. For information on how to add support for new boards, see [Adding Board Support](#adding-board-support) below.

## Quick Reference

| Platform | Families | Status | Notes |
|----------|----------|--------|-------|
| **ESP32** | ESP32, ESP32-C3, ESP32-S3 | ✅ Fully Supported | Uses ESP-IDF UART abstraction |
| **STM32** | All STM32 families | ✅ Supported | See [STM32 Details](#stm32) for specifics |
| **AVR** | Arduino | 🟡 Planned | Fallback support via Arduino FW |

---

## Platform Details

### ESP32

**Status**: Fully supported

All ESP32 variants use the ESP-IDF framework's UART abstraction, making them straightforward to support. The same code base works across all ESP32 chips.

#### Tested Development Boards
The following boards have been tested and verified with `jescore`:

| Board | PlatformIO ID | Status |
|-------|----------------|--------|
| AZ-Delivery DevKit V4 | `az-delivery-devkit-v4` | ✅ Tested |
| ESP32-WROVER-KIT | `esp-wrover-kit` | ✅ Tested |
| NodeMCU-32S | `nodemcu-32s` | ✅ Tested |
| ESP32-C3-DevKitM-1 | `esp32-c3-devkitm-1` | ✅ Tested |
| ESP32-S3-DevKitC-1 | `esp32-s3-devkitc-1` | ✅ Tested |
| Heltec WiFi LoRa 32 V3 | `heltec_wifi_lora_32_V3` | ✅ Tested |

#### Default UART Configuration
- UART Peripheral: `UART_NUM_0` (can be customized with `-DBASE_UART=UART_NUM_<n>`)
- To use a custom UART: Define `JES_UART_CUSTOM` and set `BASE_UART` in your `platformio.ini`:
  ```ini
  build_flags = -DJES_UART_CUSTOM -DBASE_UART=UART_NUM_1
  ```

---

### STM32

**Status**: Supported with board-specific UART configurations

STM32 support is more complex due to the wide variety of chip families and board layouts. `jescore` supports all STM32 families, but UART configuration must be provided for each specific board or family.

#### Supported STM32 Families

The following STM32 chip families have header includes in `board_parser.h`:

| Family | Header | UART Defaults | Status |
|--------|--------|---------------|--------|
| STM32C0 | `stm32c0xx.h` | Custom required | ✅ Compile support |
| STM32F0 | `stm32f0xx.h` | Custom required | ✅ Compile support |
| STM32F1 | `stm32f1xx.h` | Custom required | ✅ Compile support |
| STM32F2 | `stm32f2xx.h` | Custom required | ✅ Compile support |
| STM32F3 | `stm32f3xx.h` | Custom required | ✅ Compile support |
| STM32F4 | `stm32f4xx.h` | Custom required | ✅ Compile support |
| STM32F7 | `stm32f7xx.h` | Custom required | ✅ Compile support |
| STM32G0 | `stm32g0xx.h` | Custom required | ✅ Compile support |
| **STM32G4** | `stm32g431xx.h` | **Pre-configured for G431** | ✅ Fully tested |
| STM32H5 | `stm32h5xx.h` | Custom required | ✅ Compile support |
| **STM32H7** | `stm32h7xx.h` | **Pre-configured for H753** | ✅ Fully tested |
| STM32L0 | `stm32l0xx.h` | Custom required | ✅ Compile support |
| STM32L1 | `stm32l1xx.h` | Custom required | ✅ Compile support |
| **STM32L4** | `stm32l4xx.h` | **Pre-configured for L432, L476** | ✅ Fully tested |
| STM32L5 | `stm32l5xx.h` | Custom required | ✅ Compile support |
| STM32N6 | `stm32n6xx.h` | Custom required | ✅ Compile support |
| STM32U0 | `stm32u0xx.h` | Custom required | ✅ Compile support |
| STM32U5 | `stm32u5xx.h` | Custom required | ✅ Compile support |
| STM32WBA | `stm32wbaxx.h` | Custom required | ✅ Compile support |
| STM32WB | `stm32wbxx.h` | Custom required | ✅ Compile support |
| STM32WL | `stm32wlxx.h` | Custom required | ✅ Compile support |

#### Pre-configured Boards

The following boards have built-in UART configurations and do **not** require custom configuration:

| Board | Chip | PlatformIO ID | Default UART | Platform Name |
|-------|------|----------------|--------------|----------------|
| Nucleo-L432KC | STM32L432KC | `nucleo_l432kc` | USART2 | STM32L432 |
| Nucleo-L476RG | STM32L476RG | `nucleo_l476rg` | USART2 | STM32L476 |
| Nucleo-G431KB | STM32G431KB | `nucleo_g431kb` | USART2 | STM32G431 |
| Nucleo-H753ZI | STM32H753ZI | `nucleo_h753zi` | USART3 | STM32H753 |

#### Tested Development Boards

| Board | Chip | PlatformIO ID | Status |
|-------|------|----------------|--------|
| Nucleo-L432KC | STM32L432KC | `nucleo_l432kc` | ✅ Tested |
| Nucleo-L476RG | STM32L476RG | `nucleo_l476rg` | ✅ Tested |
| Nucleo-G431KB | STM32G431KB | `nucleo_g431kb` | ✅ Tested |
| Nucleo-H753ZI | STM32H753ZI | `nucleo_h753zi` | ✅ Tested |

---

## Adding Board Support

### For ESP32 Boards

ESP32 boards typically require no additional configuration. Simply:

1. Add the board to your `platformio.ini`:
   ```ini
   [env:my_esp32_board]
   platform = espressif32
   board = my_esp32_board_id
   framework = arduino
   lib_deps = jescore
   ```

2. If you need a custom UART peripheral number (other than UART_NUM_0):
   ```ini
   build_flags = -DJES_UART_CUSTOM -DBASE_UART=UART_NUM_1
   ```
   > **Note**: For ESP32, `JES_UART_CUSTOM` only requires defining `BASE_UART`. No `uart_cfg.h` file is needed.

### For STM32 Boards

STM32 boards require UART configuration macros. There are two approaches:

#### Option 1: Open an issue or DIY
You can open a PR with tested modifications to `board_parser.h` or [request support](#requesting-new-board-support). This has the benefit of expanding the core and helping others as a side-effect.

#### Option 2: Custom UART Configuration
For boards not pre-configured, create a `uart_cfg.h` file in your project with the following macros:

```c
#ifndef _UART_CFG_H_
#define _UART_CFG_H_

// Platform name (optional, defaults to "STM32")
#define BUILD_PLATFORM_NAME "STM32L452CE"

// UART Clock Configuration
#define USART_RCC_PERIPH RCC_PERIPHCLK_USART2
#define USART_CLK_SRC_DEFAULT(PeriphClkInit_struct) PeriphClkInit_struct.Usart2ClockSelection = __HAL_RCC_GET_USART2_SOURCE()

// UART Enable/Disable
#define USART_CLK_ENABLE() __HAL_RCC_USART2_CLK_ENABLE()
#define USART_CLK_GPIO_ENABLE() __HAL_RCC_GPIOA_CLK_ENABLE()
#define USART_CLK_GPIO_DISABLE() __USART2_CLK_DISABLE()

// UART Peripheral
#define USART_NUM USART2

// GPIO Configuration
#define USART_GPIO_TX_PORT GPIOA
#define USART_GPIO_RX_PORT GPIOA
#define USART_GPIO_TX_NUM GPIO_PIN_2
#define USART_GPIO_RX_NUM GPIO_PIN_3
#define USART_GPIO_TX_ALT GPIO_AF7_USART2
#define USART_GPIO_RX_ALT GPIO_AF7_USART2

// IRQ Configuration
#define USART_IRQn_NUM USART2_IRQn

#endif // _UART_CFG_H_
```

Then enable custom UART in your `platformio.ini`:
```ini
build_flags = -DJES_UART_CUSTOM
```

And ensure `uart_cfg.h` is in your include path.

---

## Board Support Matrix

| Board | Chip | Platform | CLI Support | Tested | Notes |
|-------|------|----------|-------------|--------|-------|
| AZ-Delivery DevKit V4 | ESP32 | ESP32 | ✅ Yes | ✅ Yes | |
| ESP32-WROVER-KIT | ESP32 | ESP32 | ✅ Yes | ✅ Yes | |
| NodeMCU-32S | ESP32 | ESP32 | ✅ Yes | ✅ Yes | |
| ESP32-C3-DevKitM-1 | ESP32-C3 | ESP32 | ✅ Yes | ✅ Yes | |
| ESP32-S3-DevKitC-1 | ESP32-S3 | ESP32 | ✅ Yes | ✅ Yes | |
| Heltec WiFi LoRa 32 V3 | ESP32 | ESP32 | ✅ Yes | ✅ Yes | |
| Nucleo-L432KC | STM32L432KC | STM32 | ✅ Yes | ✅ Yes | Pre-configured |
| Nucleo-L476RG | STM32L476RG | STM32 | ✅ Yes | ✅ Yes | Pre-configured |
| Nucleo-G431KB | STM32G431KB | STM32 | ✅ Yes | ✅ Yes | Pre-configured |
| Nucleo-H753ZI | STM32H753ZI | STM32 | ✅ Yes | ✅ Yes | Pre-configured |

---

## Requesting New Board Support

If you need support for a board not listed here:

1. **For ESP32**: It likely already works! Just try it and report any issues.
2. **For STM32**: Provide the UART configuration macros (see above) via a PR or issue.
3. **For other platforms**: Open an issue with your use case and board details.

---

## See Also

- [API Documentation](API-Documentation.md)
- [Backend Documentation](Backend-Documentation.md)
- [Examples](Examples.md)