Repository navigation
Rotary Encoders
RotaryEncoder uses a native counter peripheral before considering GPIO
software decoding. The same C# API supports EC11 / KY-040-style A/B controls and
an optional active-low push button.
| Port | Preferred backend | When GPIO fallback is used |
|---|---|---|
| ESP-IDF ESP32 family | PCNT quadrature channels, x4 counting; SDK overflow accumulation on IDF ≥5.1 | SoC has no PCNT (for example ESP32-C2). |
| Arduino-ESP32 | PCNT, including the legacy IDF 4.x driver in Arduino-ESP32 2.x | SoC has no PCNT. |
| STM32 Cube HAL | TIM encoder mode TI12, using a CubeMX-bound CH1/CH2 pair | No native timer binding for the requested pair. |
| RP2040 / RP2350, Arduino-Pico (non-mbed) | PIO state machine maintains a 32-bit quadrature count independently of the CPU | Pins are not a consecutive pair in GPIO 0–31, or no PIO backend is compiled. |
| Zephyr / other Arduino cores / custom ports | Board-supplied native HAL counter hooks, if present | No native backend is bound. The supplied generic Zephyr/other-core adapters currently use GPIO fallback. |
| Simulator | GPIO fallback | No physical counter peripheral. |
PIO is programmable hardware offload, not a dedicated QEI peripheral and not a CPU GPIO ISR. Native PCNT/TIM/PIO paths do not enable A/B GPIO interrupts or run C# callbacks on every transition. PCNT and 16-bit TIM use infrequent counter-limit interrupts for count extension; PIO and 32-bit TIM need no rollover ISR.
Connect common to GND, A/CLK and B/DT to suitable MCU pins, and optionally SW to another input. Use the MCU's logic voltage; do not feed 5 V to non-tolerant pins. PCNT / PIO / GPIO fallback configure pull-ups. For TIM, configure pull-up alternate function inputs in CubeMX: the constructor preserves those AF settings.
// ESP32 example: choose pins that are actually available on your board.
var encoder = new RotaryEncoder(32, 33, 4, 25);
try
{
Console.WriteLine($"Encoder backend: {encoder.Backend}"); // PCNT, TIM, PIO or Software
int previous = encoder.Position;
for (int i = 0; i < 1000; i++)
{
int position = encoder.Position;
if (position != previous)
{
Console.WriteLine($"position:{position}");
previous = position;
}
Thread.Sleep(10);
}
}
finally { encoder.Dispose(); }Constructor: new RotaryEncoder(a, b, steps = 4, button = -1, reverse = false).
Pins are numbers or board names. A/B/button must differ. steps is transitions
per reported count: 1, 2 or 4, not the encoder's advertised pulses/revolution.
Start with 4 for a typical mechanical encoder. -1 omits the button. Direction
also depends on wiring / TIM input polarity; reverse = true flips the result.
| Member | Behavior |
|---|---|
Backend |
Actual selection: PCNT, TIM, PIO, Software, or a custom HAL backend name. No guessing from the chip name. |
Position |
Signed 32-bit position. Native raw x4 counts are scaled with a retained partial remainder. Results saturate at signed 32-bit limits when sampled. |
Reset(position = 0) |
Rebaselines the native counter and clears the partial remainder without stopping or clearing the peripheral. No transitions are lost to a stop/clear/restart sequence. |
ButtonPressed |
Raw active-low optional input, false if omitted. Debounce in the application; Studio's template includes a simple stable-press reset. |
Dispose() |
Stops/releases the native counter or fallback IRQs and releases pin reservations. Idempotent. Other members then throw ObjectDisposedException. |
Hal.Has("RotaryEncoder") reports API availability; Backend identifies the
counter actually selected for that instance. A busy counter, allocation failure,
invalid configuration or read failure raises an error. These errors never
silently downgrade to software. Only “not supported for this pair / board”
selects fallback. Incomplete native HAL hook sets also raise an error.
CubeMX must configure a suitable timer in Encoder Mode TI1 and TI2 (TI12), CH1=A and CH2=B, prescaler 0, appropriate AF inputs/pull-ups and input filtering. The port uses the timer's full 16/32-bit counter range. The handle must not already be running. Bind the exact MicroCS pin pair in the board table:
// Example only: check TIM2 CH1/CH2 mapping for your exact MCU/package.
MX_TIM2_Init();
board.encoder[0] = (mcs_stm32_encoder_t){ .h = &htim2, .a = 0, .b = 1 }; // PA0 / PA1For a 16-bit timer, enable its update/global IRQ in CubeMX, have the generated
IRQ handler call HAL_TIM_IRQHandler, and forward HAL_TIM_PeriodElapsedCallback
to mcs_stm32_tim_elapsed(htim) (or set MCS_STM32_DEFINE_TIM_CALLBACK=1 when the
port owns that callback). This extends wraps without a CPU interrupt per A/B
edge. A 32-bit timer, e.g. TIM2/TIM5 where available, does not need update IRQs for
count extension. Native TIM pins do not need different EXTI lines; that
restriction applies only to GPIO fallback. No binding means fallback, not an
automatically guessed pinmux.
Timer/PWM start, configure and stop operations reject a timer currently owned by
an encoder, including aliases of the same peripheral. Native open rejects an
already running timer. Use a dedicated encoder handle and don't reconfigure it
from native SDK code while open. The port never calls GPIO.Mode on native TIM
A/B pins, which would otherwise destroy their alternate-function configuration.
At most MCS_HAL_MAX_ENCODERS (default 4, process-wide) may be open. Each uses one
small pool-accounted userdata and one VM pin handle, allocated only when opened.
Native SDK resources are separate, reflected in device heap telemetry; they are
not a second VM pool. There is no per-transition VM allocation or callback queue.
Always use try/finally: live encoders remain pinned until disposed or HAL/VM
shutdown. Failed initialization releases acquired resources. HAL close/rebind
and VM destruction also release the encoder.
PCNT claims its SDK unit/channels; PIO claims an SM and a shared 24-instruction
program at offset 0, trying available PIO blocks without evicting other programs.
Busy peripherals report an error. On legacy IDF 4.x, reserve PCNT units
0 .. min(MCS_HAL_MAX_ENCODERS, PCNT_UNIT_MAX)-1 for MicroCS: that SDK has no
public unit-claim allocator. Its shared ISR service is initialized once, not once
per upload. Do not reuse those units from native code.
GPIO/Pin mode changes, writes and IRQ changes on reserved pins are rejected;
an existing GPIO callback prevents encoder open. Other peripheral APIs are not
a global pin multiplexer: don't give encoder pins to SPI, PWM or native code.
Only the main event VM may own encoders, not MCS_HAL_NO_EVENTS workers.
- PCNT counts in hardware while C# is busy. Its 16-bit limit events must still be serviced before another 32,767-transition limit interval can be lost. IDF ≥5.1 uses the SDK's accumulator; older SDKs extend at limit IRQs, not GPIO edges.
- A 16-bit TIM must service overflow/underflow within half a counter lap (32,768 transitions). The read path accounts for a pending update flag without double counting. This cannot reconstruct multiple wraps while interrupts are masked.
- PIO maintains a modulo-32-bit count and uses a nonblocking snapshot FIFO: a full FIFO does not stall counting. Sampling is set for up to roughly 100k transitions/s; pulses below the sampling interval can be missed. Supported native pairs are consecutive pins in GPIO 0–31 with PIO GPIO base 0.
- Read native
Position/ callResetat least once per 2^31 raw transitions so signed modular deltas remain unambiguous. This is about 536 million detents at four transitions/count. Low-power modes that gate the peripheral clock can stop counting; normalThread.Sleepdoes not reconfigure that clock. - GPIO fallback samples both pins in the producer ISR, before event enqueue. Valid Gray transitions cancel back-and-forth chatter; illegal two-bit jumps resynchronize. It needs IRQ-capable pins (distinct STM32 EXTI lines), ISR-safe direct GPIO reads, and timely servicing on each edge. It is not high-speed hardware counting. PCNT/TIM filters follow their peripheral behavior instead of claiming software Gray-table invalid-transition detection.
The template is intended for human-operated controls. This is not a blanket lossless motor-feedback guarantee during flash/cache stalls or long masked IRQs. ESP32 native PCNT setup/filtering and STM32 encoder input filtering also differ from application push-button debounce.
MCS_ENABLE_ENCODER defaults to MCS_ENABLE_HAL. CMake:
-DMICROCS_ENCODER=OFF; ESP-IDF menuconfig: MicroCS → Rotary encoders.
MCS_ENABLE_ENCODER_HW defaults on with the encoder feature. Setting it to 0
explicitly forces GPIO-only firmware. The Cortex-M0 reference emulator has no
physical counter and builds GPIO fallback only, keeping its fixed flash limit.
HAL API v6 appends native encoder_open/read/close and an optional encoder_name.
open(ctx, a, b, &handle) owns native A/B electrical/AF setup. Return ENOTSUP
only when unavailable for the pair, with handle=NULL and no retained resources.
Other failures propagate. read returns a free-running modulo-32-bit x4 raw
transition total without clearing it. close stops and releases all owned native
resources. Native hooks may be supplied by a custom board, including Zephyr QDEC
adapters; none are falsely synthesized from chip capabilities.
For fallback, set gpio_capture=true only with ISR-safe direct GPIO reads and
invoke this in the GPIO ISR, before a shared or private SDK event queue:
if (!mcs_hal_gpio_edge(hal->ctx, pin))
mcs_hal_post(MCS_HAL_EV_GPIO, pin, level);The exact HAL context identifies the board. Bare-metal fallback IRQs must run on the VM core or share an IRQ-safe multicore lock. Board tables must outlive VMs.
Generated from the MicroCS repository (source branch · revision 37bd1f1). Edit the source files, not the wiki.
Start here
Step-by-step guides
- Guides
- Guide PC Simulator
- Guide ESP32
- Guide ESP32 C3 OLED
- Guide Raspberry Pi Pico
- Guide STM32
- Guide Arduino
- Guide Zephyr
- Guide Peripheral Settings
- Guide DMA
Hardware
- Hardware API
- Power Management
- Bluetooth LE
- CAN Bus
- Rotary Encoders
- Peripheral Configuration
- DMA
- Device Drivers
- Wi Fi and Networking
- U8g2 Displays
- LVGL Graphics
- Filesystem
- Threads
- Scheduler
Ports
- Porting and Build Systems
- Port ESP32
- Port RP2040 RP2350
- Port STM32
- Port STM32 Firmware
- Port Zephyr
- Port NuttX
- Port Arduino
C# and the runtime
- Language
- Standard Library
- JSON
- Standalone Firmware
- MicroCS Studio
- Web Flasher
- Studio Template Authoring
- Examples
- LVGL Examples
Embedding and tuning
- Embedding
- Configuration
- Small MCUs
- Memory Budgets
- Low RAM Firmware Example
- Performance
- Runtime Benchmark Comparison
- Lua Host Benchmark
Internals
Project