forte4esp32

中文文档索引

forte4esp32 is an ESP32-S3 adaptation of Eclipse 4diac FORTE based on ESP-IDF v6.0.

It provides a usable baseline for running FORTE on ESP32-S3 with 4diac IDE 3.1, including deploy/monitor workflow, GPIO-backed stdfblib/io support, and boot-file persistence through SPIFFS.

This repository keeps the upstream 4diac-forte submodule unmodified and limits the validated baseline to ESP32-S3.

Development workflow

The intended workflow for a developer is:

1. install ESP-IDF v6.0 with Espressif IDF Manager
2. clone this repository with submodules
3. open the repository root in VS Code
4. install and configure the ESP-IDF VS Code extension
5. select the ESP-IDF v6.0 environment for this workspace
6. build, flash, and monitor from VS Code
7. adjust runtime settings through menuconfig when needed

Typical clone command:

• git clone --recurse-submodules git@github.com:skawu/forte4esp32.git

Current status

The current main branch has been verified to:

• build and flash on ESP32-S3 with ESP-IDF v6.0
• bring up Wi-Fi station mode and acquire an IP address
• start a FORTE runtime instance on the ESP32
• listen for 4diac IDE management connections on 0.0.0.0:61499
• deploy 4diac IDE demo projects
• exchange runtime data through multicast and unicast demo variants
• run GPIO loopback validation through stdfblib/io IX/IE/QX
• expose GPIO-backed IB/QB/IW/QW/ID/QD/IL/QL process interfaces for multi-bit digital IO
• optionally autoload a pre-provisioned FORTE boot file from SPIFFS on startup
• automatically restart the FORTE runtime if it is remotely stopped

Release intent for v1.0.0:

• freeze the current ESP32-S3 + ESP-IDF v6.0 baseline
• keep the upstream 4diac-forte submodule unmodified
• ship the currently verified stdfblib/events, stdfblib/net, and GPIO-backed stdfblib/io subset
• document current limits explicitly instead of expanding scope further before release

Repository layout

• components/forte/ ESP32 integration layer and FORTE component wrapper
• components/forte/third_party/4diac-forte/ upstream 4diac FORTE submodule
• components/forte/platform/esp32/esp32_forte_sources.cmake source manifest for the ESP32 build
• main/ application entry point and optional Wi-Fi bring-up
• partitions.csv custom partition table sized for the current FORTE image
• sdkconfig.defaults default flash and partition settings
• examples/ committed 4diac IDE demo projects
• docs/ detailed 4diac IDE workflow and integration notes including adaptation status, release notes, and engineering-readiness planning

License

This repository is licensed under Apache-2.0 for the code and documentation maintained in this repository.

The upstream submodule at components/forte/third_party/4diac-forte/ keeps its own upstream license and is not relicensed by this repository.

Build assumptions

• target board: ESP32-S3
• flash size: 16MB
• partition table: custom partitions.csv
• validated ESP-IDF version: v6.0

Build and flash

This repository is intended to work directly from VS Code after the ESP-IDF extension is installed and bound to ESP-IDF v6.0.

Typical VS Code flow:

1. ESP-IDF: Select Port
2. ESP-IDF: Set Espressif Device Target -> esp32s3
3. ESP-IDF: SDK Configuration Editor (Menuconfig)
4. ESP-IDF: Build your project
5. ESP-IDF: Flash your project
6. ESP-IDF: Monitor your device

The validated defaults are already carried in:

• sdkconfig.defaults
• sdkconfig.release.defaults
• partitions.csv

Use sdkconfig.defaults as the development baseline.

Use sdkconfig.release.defaults as an overlay when evaluating a tighter release-oriented build profile, for example:

• idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.release.defaults" build

First-time bring-up

For a first successful run on a fresh machine:

1. clone the repository with submodules
2. open the repository in VS Code
3. make sure the ESP-IDF extension is using ESP-IDF v6.0
4. select target esp32s3
5. select the serial port of the board
6. open menuconfig
7. if Wi-Fi startup is needed, fill in the Wi-Fi settings under WiFi Configuration
8. build
9. flash
10. open the serial monitor

Typical success indicators:

• Wi-Fi connected, got IP: ...
• FORTE global initialization complete
• FORTE instance started on 0.0.0.0:61499
• CBSDSocketInterface: Opening TCP-Server connection at: 0.0.0.0:61499

If Wi-Fi is disabled, the Wi-Fi log line is absent, but the FORTE startup lines should still appear.

Wi-Fi bring-up

Wi-Fi station startup is controlled through menuconfig.

Path:

• WiFi Configuration

Required settings:

• Enable Wi-Fi station bring-up before starting FORTE
• Wi-Fi SSID
• Wi-Fi password

Optional diagnostics:

• Enable verbose Wi-Fi diagnostics

Keep verbose Wi-Fi diagnostics disabled for normal use. Enable it only for troubleshooting.

Demo projects

The repository includes complete 4diac IDE projects here:

• examples/DistributedBlink/DistributedBlink.sys
• examples/IOByteLoopback/IOByteLoopback.sys
• examples/IOEventInput/IOEventInput.sys
• examples/IODigitalLoopback/IODigitalLoopback.sys
• examples/SingleDeviceBlink/SingleDeviceBlink.sys
• examples/UnicastBlink/UnicastBlink.sys
• examples/DistributedBlink/README.md
• examples/DistributedBlink/README_CN.md
• examples/IOByteLoopback/README.md
• examples/IOByteLoopback/README_CN.md
• examples/IOEventInput/README.md
• examples/IOEventInput/README_CN.md
• examples/IODigitalLoopback/README.md
• examples/IODigitalLoopback/README_CN.md
• examples/SingleDeviceBlink/README.md
• examples/SingleDeviceBlink/README_CN.md
• examples/UnicastBlink/README.md
• examples/UnicastBlink/README_CN.md

Detailed 4diac IDE workflow documents:

• docs/README.md
• docs/cn/README.md
• docs/getting_started.md
• docs/cn/getting_started.md
• docs/esp32_4diac_v31_tutorial.md
• docs/cn/esp32_4diac_v31_tutorial.md
• docs/4diac_ide_workflow.md
• docs/cn/4diac_ide_workflow.md
• docs/boot_file_autoload.md
• docs/cn/boot_file_autoload.md
• docs/custom_fb_workflow.md
• docs/cn/custom_fb_workflow.md
• docs/port_status.md
• docs/cn/port_status.md
• docs/known_limitations.md
• docs/cn/known_limitations.md
• docs/release_checklist.md
• docs/cn/release_checklist.md
• docs/release_notes_v1.0.0.md
• docs/cn/release_notes_v1.0.0.md

Preferred demos:

• DistributedBlink two runtimes, multicast transport, PUBLISH_1 / SUBSCRIBE_1
• IOByteLoopback one runtime, QB/IB byte-wide GPIO loopback validation
• IOEventInput one runtime, IE.IND input-event validation through GPIO loopback
• IODigitalLoopback one runtime, GPIO loopback validation with eclipse4diac::io::QX and IX
• SingleDeviceBlink one runtime, no inter-device communication
• UnicastBlink two runtimes, TCP point-to-point transport, SEND_RECV_1_1

Naming note:

• repository examples use functional names without the Test suffix

stdfblib/io support

This ESP32 port currently supports a GPIO-backed subset of stdfblib/io:

• eclipse4diac::io::IX
• eclipse4diac::io::IE
• eclipse4diac::io::QX
• eclipse4diac::io::IB
• eclipse4diac::io::QB
• eclipse4diac::io::IW
• eclipse4diac::io::QW
• eclipse4diac::io::ID
• eclipse4diac::io::QD
• eclipse4diac::io::IL
• eclipse4diac::io::QL

Supported PARAMS formats:

• '<gpio_num>'
• 'GPIO_NUM=<gpio_num>'
• optional flags: 'INVERT=1', 'PULLUP=1', 'PULLDOWN=1'
• 'GPIO_NUMS=<gpio0>|<gpio1>|...|<gpioN>'
• 'GPIO_BASE=<gpio_start>,WIDTH=<bit_width>'

Current width expectations:

• IX/IE/QX use exactly 1 GPIO
• IB/QB use exactly 8 GPIOs
• IW/QW use exactly 16 GPIOs
• ID/QD use exactly 32 GPIOs
• IL/QL use exactly 64 GPIOs

Bit ordering is LSB-first:

• the first configured GPIO maps to bit 0
• the second configured GPIO maps to bit 1
• and so on

Current input-event behavior:

• IX/IB/IW/ID/IL update their IN outputs on REQ
• IX/IB/IW/ID/IL/IE also emit IND on detected input changes
• GPIO-backed input change detection is currently poll-based, not hardware-interrupt-based

The runtime implementation is board-agnostic. The validated board-level loopback demo in this repository currently uses ESP32-S3-DevKitM-1 with:

• QX.PARAMS = 'GPIO_NUM=35'
• IX.PARAMS = 'GPIO_NUM=36,PULLUP=1'

About multicast vs. unicast

According to the official 4diac FBDK/IP documentation:

• PUBLISH_1 / SUBSCRIBE_1 use UDP multicast
• the ID should be a multicast address such as 239.0.0.1:61000

Sources:

• https://eclipse.dev/4diac/doc/communication/fbdkip.html
• https://eclipse.dev/4diac/doc/tutorials/distribute4diac.html

Practical implication:

• DistributedBlink stays multicast-based
• UnicastBlink exists as a separate topology-friendly alternative

Runtime behavior

The ESP32 FORTE task runs under a simple supervisor loop.

If a remote management action stops the runtime:

• the current FORTE status is logged
• the task waits 1 second
• the runtime is started again

Known behavior

• 4diac IDE deploy and monitoring work against the validated runtime
• the remote runtime may still be explicitly stopped by management-side actions
• the ESP32 automatically recovers by restarting FORTE
• multicast behavior depends on the network topology
• 4diac IDE deploy is session-based and is not persisted across power cycles unless boot-file autoload is explicitly enabled and a boot file has been provisioned into SPIFFS
• the current validated image fully occupies IRAM under ESP-IDF v6.0; this is a release risk and should be treated as a hard limit for v1.0.0

Minimum release validation

The minimum validation target for v1.0.0 is:

1. clean build on ESP-IDF v6.0
2. flash and runtime startup on ESP32-S3
3. 4diac IDE deploy using SingleDeviceBlink
4. 4diac IDE monitor using SingleDeviceBlink
5. GPIO loopback validation using IODigitalLoopback
6. boot-file export and boot-file autoload validation

Boot file autoload

This repository now includes a phase-1 persistent startup path for FORTE:

• optional SPIFFS-backed boot-file autoload on startup
• default boot-file path: /spiffs/forte.fboot
• provisioning source directory: components/forte/bootfs/

Scope:

• supported: autoloading a pre-provisioned boot file during startup
• supported: optional HTTP upload of a generated .fboot into SPIFFS
• not yet supported: automatically converting a live 4diac IDE deploy into a boot file and saving it back into Flash

See:

• docs/boot_file_autoload.md
• docs/cn/boot_file_autoload.md