Embedded firmware technical documentation.

JG-01

Embedded Firmware Technical Documentation

ESP32-S3 • Murata SCH16T • BLE • OTA • Real-Time Steering Control

Revision History

Document Basis and Limitations

This document is derived from the supplied firmware source archive. It describes the implementation as found in the code rather than an intended future architecture. Where comments and executable values disagree, the executable value is treated as authoritative and the discrepancy is called out explicitly.

Table of Contents

1. Introduction

2. Firmware Organization

3. System Architecture

4. Startup and Initialization

5. Real-Time Execution Model

6. Main Control Algorithm

7. Sensor Subsystem

8. Receiver Inputs

9. Servo Output and Dual-Servo Mixing

10. Settings, Profiles, and Persistence

11. BLE, JSON API, and OTA

12. Web/Settings Runtime

13. Logging Subsystem

14. LED and Operator Feedback

15. Concurrency and Shared State

16. Module Reference

17. Design Assessment and Observations

Appendix A. Parameter Catalogue

Appendix B. JSON Command Catalogue

Appendix C. Pin and Timing Summary

1. Introduction

1.1 Purpose

The JG-01 firmware implements a steering-assistance controller for a rear-wheel-drive RC drift vehicle. It acquires steering, gain, and throttle commands from the radio receiver; measures vehicle yaw rate and acceleration using a Murata SCH16T inertial sensor; calculates a corrective steering component; and drives one or two steering servos. The same firmware also provides configuration, profile storage, BLE communication, firmware update, web/settings functions, diagnostics, and SD-card logging.

1.2 Scope

Source-code structure and module responsibilities.

ESP32-S3 startup, FreeRTOS tasks, interrupt timing, and core assignment.

The complete 400 Hz control-cycle data path.

IMU, receiver, servo, profile, BLE, OTA, settings, and logging behavior.

Concurrency controls and implementation observations relevant to maintenance.

1.3 Key implementation facts

2. Firmware Organization

The project is organized as one main Arduino sketch plus focused C++ modules. The main sketch owns the physical control path and top-level state. Supporting modules encapsulate sensor access, configuration transport, parameter validation, filtering, drift detection, return damping, receiver decoding, and logging.

Figure 1. Major firmware subsystems and their data relationships.

2.1 Source groups

2.2 Main-sketch ownership

The main sketch is deliberately central. It creates the SCH16T object, servo objects, filters, detectors, task handles, hardware timer, receiver pulse state, live telemetry, profile state, and the active ControlParams instance. This makes the time-critical path easy to follow, but it also means rc_drift_gyro_01.ino is the primary integration point and carries substantial global state.

3. System Architecture

The firmware separates the high-rate steering loop from lower-rate management work. Core 1 is reserved for the timer-triggered control task. Core 0 runs status indication and the communications/settings task. Logging creates an additional task on a caller-selected core when recording begins.

Figure 2. FreeRTOS tasks, core placement, priorities, and principal responsibilities.

3.1 Data path

Receiver signals are captured either by GPIO edge interrupts or by iBus UART parsing.

The control task wakes from a hardware-timer notification every 2.5 ms.

The task snapshots current settings, reads inputs, and normalizes steering and throttle.

SCH16T data is acquired and transformed into the selected installation orientation.

Yaw-rate and acceleration signals pass through configurable filters and derivative processing.

The P+D control calculation is shaped by drift detection, steering priority, correction exponent, lateral-acceleration assistance, peak holding, low-pass filtering, and a delta limiter.

The correction is added to driver steering, constrained by EPA, filtered, optionally mapped to two servos, and written as PWM.

Every fourth control cycle a telemetry record is offered to the logging queue.

4. Startup and Initialization

Figure 3. Startup order implemented in setup().

4.1 Startup order

Start the serial port at 115200 baud and select slow LED blinking.

Initialize LED PWM immediately, then load stored settings.

Create ledTask on core 0 at priority 1.

Create wifiTask on core 0 at priority 4 before IMU startup. This intentionally keeps settings and OTA access available even if the IMU is absent or calibration fails.

Start SPI and configure SCH16T filter, sensitivity, and decimation structures from the loaded settings.

Attempt IMU initialization for up to 2 seconds. If initialization fails, setup() returns without starting the control task. Communications remain available because wifiTask is already running.

Initialize either iBus or three GPIO pulse inputs.

Run IMU calibration with a 5-second timeout. The control task is still permitted to start if calibration does not complete.

Configure two servo objects with 14-bit timer width and the validated servo frequency.

Reload settings, create controlTask on core 1, and start the periodic hardware timer.

Set LED brightness and indicate whether the base or secondary runtime profile is active.

4.2 Fault behavior during startup

5. Real-Time Execution Model

5.1 Hardware timer and task notification

Timer 0 is configured with an 80:1 prescaler, producing a 1 MHz timer tick. Its auto-reload alarm is set to LOOP_PERIOD_US = 2500. The interrupt service routine calls vTaskNotifyGiveFromISR() for controlTask and requests a context switch when necessary. The task blocks indefinitely in ulTaskNotifyTake() and therefore consumes no CPU while waiting.

The executable period is 2.5 ms, or 400 Hz. A nearby source comment says “5 ms = 200 Hz”; that comment is stale and does not match the constant or timer configuration.

5.2 Task inventory

5.3 Timing behavior

The control task calculates measured dt from micros() for manual dual-servo ramping, while filter/derivative objects also use the configured nominal loop period in several places.

No blocking delay appears in the main control cycle. SD writes are delegated through a non-blocking queue.

Serial debug printing is rate limited to approximately 5 Hz and additionally suppressed when receiver input activity is recent, reducing interference with pulse capture.

The Arduino loop() is intentionally idle and sleeps for one second; application work is task-driven.

5.4 Overrun considerations

A direct task notification acts as a counting semaphore. If a control iteration exceeds 2.5 ms, notifications can accumulate, but the task has no explicit deadline-miss counter or execution-time monitor. Consequently, a sustained overrun may cause back-to-back iterations instead of preserving evenly spaced control updates. Instrumenting cycle duration and notification backlog would improve observability.

6. Main Control Algorithm

Figure 4. Processing sequence performed by each controlTask iteration.

6.1 Settings synchronization

When settings_changed is set, the control task reloads the active profile. It then copies the global ControlParams object into a local stack variable while holding cp_mux. The local snapshot prevents individual fields from changing midway through a cycle. Profile-switch logic may update the runtime profile, after which the task snapshots ControlParams again.

6.2 Receiver acquisition and normalization

PWM mode reads volatile pulse-width snapshots under s_mux. iBus mode calls ibusUpdate() and maps channel 1 to steering, channel 3 to gain, and channel 4 to throttle. Steering can be reversed around the stored EPA center. Gain is mapped from nominal 1000-2000 µs into 0.0-1.0. Steering and throttle are low-pass filtered and normalized through SteeringMap objects.

6.3 IMU processing

The task requests raw SCH16T data and converts it into engineering units. applyImuOrientation() supports eight installation orientations by swapping and negating body axes. Body Z angular rate becomes gyrodps. Body X acceleration, after removal of the lateral setpoint, becomes the lateral-acceleration assistance input.

6.4 Yaw-rate P+D correction

Yaw rate is low-pass filtered to form the proportional signal. A derivative object calculates yaw acceleration and a second low-pass filter suppresses derivative noise. The core correction is:

gyro_correction = drift_multiplier × configured_gain × receiver_gain × (pid_p × filtered_yaw_rate + pid_d × filtered_yaw_derivative)

No integral term is used. This is consistent with a drift-assistance controller where the desired behavior is rate-sensitive support rather than elimination of a persistent heading error.

6.5 Drift-dependent gain

DriftDetector receives normalized steering, filtered yaw rate, and configured gain. Its output is converted into a multiplier of 1 + (drift_value / 10) × dd_multiplier. The intention is to increase correction when steering/yaw conditions indicate an established drift.

6.6 Steering priority

The derivative of normalized driver steering reduces gyro authority during rapid manual steering movement. The correction is divided by 1 + (|steering derivative| / 2) × steering_prio. This preserves driver authority during transitions and fast counter-steering inputs.

6.7 Nonlinear shaping and acceleration assistance

correction_exp applies a sign-preserving power function normalized around a correction magnitude of 150. Values above one suppress small corrections relative to large ones; values below one do the opposite. Filtered lateral acceleration is multiplied by acc_lat_multip, clamped to ±50 µs, and added to the gyro correction.

6.8 Peak hold, filtering, and slew limiting

RollingMaxCorr stores a recent maximum-magnitude correction. For the first 60% of the configured rollmaxcorr age window, that peak is held. During the remaining 40%, the output blends back toward the current correction. A correction low-pass filter follows. Finally, max_d_corr constrains the change relative to the previous cycle, acting as a global correction slew limiter.

6.9 Output construction

The final correction is added to the filtered receiver steering pulse. When EPA is enabled, the result is clamped to the stored low/high endpoints. A servo-output low-pass filter is applied before normal or dual-servo output mapping. A deadband-like condition attempts to retain the previous output when the change is below 2 µs; however, it appears before the new out value is calculated and should be reviewed because its effective behavior may not match the apparent intent.

6.10 Logging cadence

logging_counter causes one sample to be enqueued every fourth control iteration. At a 400 Hz control rate this gives a nominal logging rate of 100 Hz. The record includes filtered and raw gyro values, correction, input/output pulses, gain input, normalized throttle, receiver gain, and three raw acceleration axes.

7. Sensor Subsystem

7.1 SCH16T configuration

7.2 Initialization and diagnostics

initializeImu() repeatedly calls imu.begin() until success or timeout. The SCH16T driver is significantly larger than the control modules and contains register-level startup, status checks, filter/sensitivity configuration, conversion, and device-identification logic. After initialization the firmware reads and prints the sensor serial number.

7.3 Calibration and orientation

Calibration establishes acceleration offsets and a lateral acceleration setpoint while the car is stationary. Eight orientation modes allow the PCB to be installed in multiple rotations and inverted configurations without rewriting the control algorithm. The orientation mapping is applied consistently before yaw and body acceleration are used.

8. Receiver Inputs

8.1 PWM mode

Steering, gain, and throttle use GPIO 3, 4, and 39. CHANGE interrupts measure high-pulse duration. Shared pulse variables are volatile and copied under s_mux in the control task. This keeps ISR work minimal and avoids disabling interrupts for longer than the snapshot operation.

8.2 iBus mode

IbusReceiver reads fixed 32-byte frames, validates the protocol checksum, extracts channel values, and maintains diagnostics including valid-frame count, checksum errors, frame errors, last-frame time, and raw-frame bytes. The normal control calculations are unchanged after channel values are selected.

8.3 Runtime profile switching

Each base profile can define a secondary profile and an iBus switch channel. The control loop evaluates the selected channel with a 100 ms debounce period and loads either the base or secondary runtime profile. The LED uses a distinct pattern while the secondary profile is active.

9. Servo Output and Dual-Servo Mixing

9.1 Servo generation

ESP32Servo is configured with 14-bit timer width. GPIO 5 drives servo 1 and GPIO 6 drives servo 2. servo_hz is validated before use; its default is 200 Hz. In single-servo mode only servo 1 is updated by the control task.

9.2 Nine-point mapping

Dual-servo mode uses nine steering input points at −100, −80, −50, −20, 0, 20, 50, 80, and 100 percent. Independent left and right tables are linearly interpolated between adjacent points. Negative and positive sides are scaled relative to their respective endpoint magnitudes. Servo 2 uses the right-side curve and then reverses sign so the two physical steering actuators can work in opposition.

9.3 Manual test mode

The settings interface can take temporary control of the servos for calibration. The requested test input is ramped at 500 µs/s using the measured cycle dt, preventing an abrupt jump. Release-to-center ramps back to 1500 µs and automatically returns ownership to the normal control path after center is reached.

10. Settings, Profiles, and Persistence

10.1 Parameter model

params_list.h is an X-macro list and is the single place where regular ControlParams fields and defaults are declared. ControlParams.h includes the list three times to initialize defaults, build a name-to-pointer table, and declare typed members. This reduces duplication and lets the SettingsService access parameters by name.

10.2 Four-profile storage

The firmware supports four profiles. Each profile uses its own Preferences namespace (rc0 through rc3), while legacy values can be read from an older rc namespace. The active base profile, profile names, secondary profile, switch channel, EPA values, dual-servo map, and common settings are loaded and saved through settings.cpp and companion routines in the main sketch.

10.3 Runtime change model

SettingsService validates incoming text, writes the typed value into ControlParams, and marks settings_changed. The control task observes that flag and reloads its active settings. The cp_mux critical section protects snapshots and settings-sensitive shared values. Persistent commands save values to Preferences; temporary set operations can modify runtime behavior without necessarily committing it.

10.4 Validation

Murata filter values are restricted to supported rates.

Servo frequency is checked by isValidServoHz()/validatedServoHz().

Known parameters are parsed by type and rejected with an error string when invalid.

BLE authentication is enforced when device_pwd is non-empty.

11. BLE, JSON API, and OTA

11.1 GATT service

The peripheral advertises a custom settings service, uses an MTU of 185, high transmit power, and conservative 40-80 ms advertising intervals intended to improve compatibility with Windows/WinRT adapters.

11.2 Request handling

BLE write callbacks do not execute the complete command directly. They store a pending request, and BluetoothSettingsTransport::loop() later removes and processes it. Authentication is handled before SettingsApi dispatch. Responses are serialized as JSON and sent by notification.

11.3 JSON command groups

11.4 BLE OTA transaction

ota_begin validates the declared image size and opens an ESP32 Update transaction. OTA Data writes raw bytes and tracks the number accepted. ota_status reports progress. ota_end verifies the completed image and schedules reboot. ota_abort terminates an active transaction. Progress notifications are intentionally not interleaved with the high-rate data callback because some Windows BLE stacks fail when notifications and firmware writes overlap.

11.5 Build identification

get_info returns firmware version, Git commit, branch, dirty-build flag, build date/time, and BLE device name. This makes field units traceable to the exact software build used.

12. Web/Settings Runtime

settings.cpp contains the browser-facing management implementation. It builds HTML pages, websocket telemetry, profile controls, logging pages, firmware-upload handlers, file download, EPA functions, dual-servo setup, Wi-Fi persistence, and settings save operations. setupSettings() initializes the subsystem; makeSettings() services it from wifiTask at approximately 20 Hz due to the 50 ms task delay.

12.1 Separation from the control loop

The communications/settings task is pinned to core 0, while the control task is pinned to core 1. This reduces the risk that HTTP, BLE, HTML construction, flash writes, or OTA processing directly delay the 400 Hz steering loop. Shared state is exchanged through snapshots, flags, and critical sections rather than by invoking browser logic from the control task.

12.2 EPA mode

EPA mode exposes live receiver pulses, captures low/center/high steering and throttle points, saves them to non-volatile storage, and can temporarily disable normal endpoint limiting. The LED blinks fast while endpoint protection is disabled, providing a visible warning.

13. Logging Subsystem

13.1 Producer-consumer design

The control task is the producer and never writes the SD card directly. loggingEnqueue() calls xQueueSend() with zero wait. If the queue is full, the sample is dropped and a counter is incremented rather than blocking control execution. LoggerTask is the consumer and performs buffered writes and file flushes.

13.2 Structures and buffering

13.3 Logged channels

The timestamp member name t_us is misleading because the assignment divides microseconds by 1000. Documentation and downstream log readers should treat it as elapsed milliseconds unless the source is changed.

14. LED and Operator Feedback

ledTask is an independent low-priority state machine using ESP32 LEDC PWM. LED_OFF and LED_ON update every 100 ms. Fast blink uses a 200 ms full period; slow blink uses 800 ms. Secondary-profile mode stays on for 800 ms and off for 200 ms. Brightness and command are copied under led_mux.

15. Concurrency and Shared State

15.1 Critical sections

15.2 Communication patterns

Direct-to-task notification: timer ISR to controlTask.

Queue: controlTask to LoggerTask.

Volatile snapshots + critical sections: receiver ISRs to controlTask.

Flag + reload: SettingsService to controlTask.

Pending request buffer: BLE callback to transport loop.

Local copy of ControlParams: stable settings for each high-rate cycle.

15.3 Risks to review

String operations and noInterrupts()/interrupts() in the BLE pending-request handoff should remain short; a queue would provide a more explicit thread-safe boundary.

settings_changed is a shared flag; making it atomic or consistently protecting it would clarify memory ordering.

Some control code uses cp directly instead of cp_local, notably drift calculation fields, which can undermine the otherwise careful per-cycle snapshot model.

There is no explicit watchdog, control-cycle deadline monitor, or receiver failsafe behavior described in the supplied main path.

LoggerTask and controlTask both use priority 3. Core selection for logging should avoid competing with control on core 1.

16. Module Reference

17. Design Assessment and Observations

17.1 Strengths

The control task is isolated on core 1 and triggered by a hardware timer rather than Arduino loop timing.

Control-cycle SD work is non-blocking and queue based.

Management/OTA is started before the IMU, allowing recovery from a sensor fault.

Settings are snapshotted for deterministic per-cycle use.

Receiver abstraction allows PWM and iBus without changing downstream control logic.

BLE separates JSON control traffic from raw OTA data.

Profiles, secondary-profile switching, EPA, and dual-servo mapping are integrated into the runtime rather than bolted onto the mobile app.

Build metadata and dropped-log-sample counters support field diagnostics.

17.2 Important code observations

17.3 Recommended verification tests

Measure controlTask execution-time distribution at 400 Hz with BLE active, web UI active, and logging active.

Verify receiver loss behavior separately for PWM and iBus.

Confirm correction sign for all eight IMU orientation modes.

Sweep yaw-rate and steering inputs to validate steering-priority and nonlinear exponent behavior.

Test rollmaxcorr peak hold and fade at boundary values 0, 1, and typical window sizes.

Verify servo update frequency and pulse timing for both single- and dual-servo operation.

Stress BLE OTA on Windows, Android, and iOS while monitoring control-task timing.

Fill the logging queue deliberately and verify dropped-sample reporting and safe stop.

Appendix A. Parameter Catalogue

Appendix B. JSON Command Catalogue

Appendix C. Pin and Timing Summary