EncButton Arduino Library

EncButton provides high-performance handling for two main hardware components:

Button Support

• Event Processing: Handles clicks, long presses, hold, pulse hold, and click counters.
• Advanced Logic: Supports 'pre-clicks' (detecting clicks that occurred before a hold event) and can treat two simultaneous button presses as a third unique button event.
• Debouncing: Includes software-based debouncing.

Encoder Support

• Event Processing: Detects normal rotation, pressed rotation (button held while turning), and fast rotation.
• Precision: Uses a high-precision algorithm for position determination.
• Compatibility: Supports four different types of incremental encoders.
• Performance: Optimized for use within interrupts and uses buffering to ensure no steps are missed.

General Characteristics

• Low Overhead: Extremely small footprint (~5 bytes SRAM per instance, ~350 bytes Flash for button processing).
• Optimized Performance: Uses fast asynchronous polling and optimized pin reading for AVR, ESP8266, and ESP32 (via GyverIO).
• Virtual Mode: Supports working with pin expanders via virtual pin mapping.

The library provides several ways to poll button interactions. Events are typically triggered once, while states can be checked continuously.

Events (Return true once per occurrence):

• press(): Button was pressed.
• release(): Button was released.
• click(): Button was clicked (released without being held).
• hold(): Button was held longer than the timeout.
• step(): Impulse hold (short hold).
• releaseHold(): Button released after a hold.
• releaseStep(): Button released after an impulse hold.
• releaseHoldStep(): Button released after either a hold or impulse hold.
• hasClicks(): Multiple clicks were detected.

States (Return true while condition is met):

• pressing(): Button is currently being pressed.
• holding(): Button is currently being held.
• waiting(): Button is waiting for more clicks to complete a multi-click sequence.
• busy(): Processing is in progress (between first press and end of click sequence).

EncButton uses a "ticker" mechanism to process signals. You must call a processing function to update the internal state and detect events.

Types of processing functions

• tick(): The standard function to be called once per loop in your main loop() function. It returns true if an event occurred (for the encoder, it returns true on any rotation).
• tickISR(): A specialized function designed to be called inside an Interrupt Service Routine (ISR) for high-precision encoder handling.

Event Polling Types

Once tick() is called, you can poll for events using two patterns:

1. [event] (One-time events): Functions like click() or turn() return true exactly once when the event occurs. They reset automatically after the next tick() call.
2. [state] (Continuous states): Functions that return true as long as a specific state is active (e.g., while a button is being held down).

Important: Do not call tick() multiple times within a single loop iteration unless you are using the attach() callback method, as subsequent calls will reset the events detected by the first call.

void loop() {
  btn.tick(); // Call once at the start of the loop

  if (btn.click()) {
    // This will execute once per click
    Serial.println("click");
  }
}

The library uses a two-step pattern: Processing (the tick function) and Polling (event functions like click(), turn(), etc.).

1. Processing (tick): This function must be called once per loop cycle. It reads the hardware pins, performs debouncing/logic, and updates the internal state. It resets event flags.
2. Polling ([event]): These functions check the state updated by tick.
   • Event functions (e.g., click(), turn()): Return true once when the event occurs and then reset.
   • State functions (e.g., hold(), fast()): Return true as long as the state is active.

Important: Do not call tick() multiple times in a single loop cycle unless you are using an event handler (attach()), as subsequent calls will reset the events from the first call before you can poll them.

void loop() {
  // 1. Process (once per cycle)
  btn.tick();

  // 2. Poll (multiple times if needed)
  if (btn.click()) Serial.println("click");
  if (btn.hold()) Serial.println("holding");
}

EncButton uses an inheritance-based architecture (an "onion" model) where higher-level classes inherit functionality from lower-level ones. To use all available functions for a class, you must also consider its parent classes.

Class Layers

1. Basic (Virtual) Classes

These classes do not specify microcontroller pins directly; they work with transmitted values (e.g., from shift registers or pin extenders).

• VirtButton: Provides all basic button features.
• VirtEncoder: Determines encoder rotation direction and fact of rotation.
• VirtEncButton: Base class for an encoder with a button; inherits VirtButton and VirtEncoder.

2. Main Classes

• Button / ButtonT: Button class (inherits VirtButton).
• Encoder / EncoderT: Encoder class (inherits VirtEncoder).
• EncButton / EncButtonT: Encoder with a button (inherits VirtEncButton, VirtButton, and VirtEncoder).

Naming Conventions

• T Suffix (e.g., ButtonT): These classes require pin numbers to be specified as constants (digits). This stores pin numbers in program memory, making the code faster and saving 1 byte of RAM per pin.
• Virt Prefix: Indicates a virtual class that operates on values rather than direct hardware pins.

The encoder tracks rotations and maintains a counter.

• Fast Rotations: A rotation is considered "fast" if it occurs within the configured timeout of the previous rotation.
• Interrupts: Rotations processed within an interrupt become active (triggering events) only after tick() is called.
• Counter Access: The counter is a public variable. You can read, modify, or reset it directly.
• Atomic Access (AVR): When accessing the 32-bit counter inside an interrupt on AVR platforms, use getCounter() and setCounter(value) to ensure atomicity.

Encoder with Button

• Rotating the encoder while the button is pressed blocks all subsequent events and clicks, except for the release event. The button's pressed state remains unchanged.
• Rotating the encoder resets the system timeout() timer; the timeout will trigger after the specified time following the last rotation.

// Direct counter manipulation
Serial.println(eb.counter); // read
eb.counter += 1234;         // modify
eb.counter = 0;            // reset