---
import '../../styles/global.css';
---
<html lang="en">
<head>
<meta charset="utf-8" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<meta name="viewport" content="width=device-width" />
<meta name="generator" content={Astro.generator} />
<title>Encoders API - PoKeys Core Library</title>
<style>
aside .sidebar-nav a {
display: block !important;
width: 100% !important;
}
aside .sidebar-nav {
display: flex !important;
flex-direction: column !important;
}
</style>
</head>
<body class="bg-gray-900 text-white">
<nav class="fixed top-0 left-0 right-0 z-50 bg-gray-900/80 backdrop-blur-md border-b border-gray-800 h-16">
<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 h-full">
<div class="flex justify-between items-center h-full">
<a href="/core/" class="text-2xl font-bold bg-gradient-to-r from-blue-400 to-purple-500 bg-clip-text text-transparent">
PoKeys
</a>
<div class="hidden md:flex space-x-8">
<a href="/core/" class="text-gray-300 hover:text-white transition-colors">Home</a>
<a href="/core/getting-started" class="text-gray-300 hover:text-white transition-colors">Getting Started</a>
<a href="/core/examples/" class="text-gray-300 hover:text-white transition-colors">Examples</a>
<a href="/core/api/" class="text-white font-semibold">API Reference</a>
</div>
</div>
</div>
</nav>
<div class="flex min-h-screen pt-16">
<aside class="w-80 bg-gray-800/50 border-r border-gray-700 overflow-y-auto flex-shrink-0">
<div class="p-6">
<a href="/core/api/" class="text-blue-400 hover:text-blue-300 mb-4 inline-block">← Back to API Reference</a>
<h2 class="text-xl font-bold mb-6 text-white">API Reference</h2>
<div class="mb-6">
<h3 class="text-sm font-semibold text-gray-400 uppercase tracking-wider mb-3">Core APIs</h3>
<div class="space-y-1 sidebar-nav">
<a href="/core/api/device" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Device Management
</a>
<a href="/core/api/connection" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Connection & Enumeration
</a>
<a href="/core/api/models" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Device Models
</a>
</div>
</div>
<div class="mb-6">
<h3 class="text-sm font-semibold text-gray-400 uppercase tracking-wider mb-3">I/O Operations</h3>
<div class="space-y-1 sidebar-nav">
<a href="/core/api/digital-io" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Digital I/O
</a>
<a href="/core/api/analog-io" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Analog I/O
</a>
<a href="/core/api/pin-functions" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Pin Functions
</a>
</div>
</div>
<div class="mb-6">
<h3 class="text-sm font-semibold text-gray-400 uppercase tracking-wider mb-3">Control Systems</h3>
<div class="space-y-1 sidebar-nav">
<a href="/core/api/pwm" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
PWM Control
</a>
<a href="/core/api/encoders" class="block px-3 py-2 text-white bg-gray-700/50 rounded-md transition-colors">
Encoders
</a>
<a href="/core/api/pulse-engine" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Pulse Engine v2
</a>
<a href="/core/api/servo-control" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Servo Control
</a>
</div>
</div>
<div class="mb-6">
<h3 class="text-sm font-semibold text-gray-400 uppercase tracking-wider mb-3">Communication</h3>
<div class="space-y-1 sidebar-nav">
<a href="/core/api/spi" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
SPI Protocol
</a>
<a href="/core/api/i2c" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
I2C Protocol
</a>
<a href="/core/api/uart" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
UART Serial
</a>
<a href="/core/api/can" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
CAN Bus
</a>
<a href="/core/api/onewire" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
1-Wire Protocol
</a>
</div>
</div>
<div class="mb-6">
<h3 class="text-sm font-semibold text-gray-400 uppercase tracking-wider mb-3">Matrix Operations</h3>
<div class="space-y-1 sidebar-nav">
<a href="/core/api/matrix-keyboard" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Matrix Keyboard
</a>
<a href="/core/api/led-matrix" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
LED Matrix
</a>
</div>
</div>
<div class="mb-6">
<h3 class="text-sm font-semibold text-gray-400 uppercase tracking-wider mb-3">Display & Sensors</h3>
<div class="space-y-1 sidebar-nav">
<a href="/core/api/lcd" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
LCD Display
</a>
<a href="/core/api/sensors" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
EasySensors
</a>
<a href="/core/api/rtc" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Real-Time Clock
</a>
</div>
</div>
<div class="mb-6">
<h3 class="text-sm font-semibold text-gray-400 uppercase tracking-wider mb-3">Error Handling</h3>
<div class="space-y-1 sidebar-nav">
<a href="/core/api/errors" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Error Types
</a>
<a href="/core/api/result-handling" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Result Handling
</a>
</div>
</div>
<div class="mb-6">
<h3 class="text-sm font-semibold text-gray-400 uppercase tracking-wider mb-3">Types & Utilities</h3>
<div class="space-y-1 sidebar-nav">
<a href="/core/api/types" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Core Types
</a>
<a href="/core/api/constants" class="block px-3 py-2 text-gray-300 hover:text-white hover:bg-gray-700/50 rounded-md transition-colors">
Constants
</a>
</div>
</div>
</div>
</aside>
<main class="flex-1 p-8 min-h-screen">
<div class="max-w-4xl">
<div class="mb-12">
<div class="flex items-center gap-4 mb-6">
<span class="px-3 py-1 bg-red-600/20 text-red-300 text-sm rounded-full">Encoders</span>
</div>
<h1 class="text-4xl font-bold mb-4 bg-gradient-to-r from-red-400 to-pink-500 bg-clip-text text-transparent">
Encoders API
</h1>
<p class="text-xl text-gray-400">
Quadrature encoder reading with 4x/2x sampling modes, position and velocity tracking
</p>
</div>
<section class="mb-12">
<h2 class="text-2xl font-bold mb-4 text-white">Overview</h2>
<div class="bg-gray-800 rounded-lg p-6">
<p class="text-gray-300 mb-4">
The Encoders API provides comprehensive support for quadrature encoders with configurable sampling modes,
position tracking, and velocity measurement. Supports both 4x and 2x sampling for different precision requirements.
</p>
<div class="grid md:grid-cols-2 gap-6">
<div>
<h3 class="text-lg font-semibold mb-2 text-red-400">Key Features</h3>
<ul class="text-gray-300 space-y-1 text-sm">
<li>• Quadrature encoder support (A/B channels)</li>
<li>• 4x and 2x sampling modes</li>
<li>• Position and velocity tracking</li>
<li>• Configurable encoder options</li>
<li>• Real-time position updates</li>
</ul>
</div>
<div>
<h3 class="text-lg font-semibold mb-2 text-pink-400">Sampling Modes</h3>
<ul class="text-gray-300 space-y-1 text-sm">
<li>• <strong>4x Sampling</strong> - Maximum precision</li>
<li>• <strong>2x Sampling</strong> - Standard precision</li>
<li>• <strong>Index Support</strong> - Optional Z channel</li>
</ul>
</div>
</div>
</div>
</section>
<section class="mb-12">
<h2 class="text-2xl font-bold mb-6 text-white">Basic Usage</h2>
<div class="bg-gray-800 rounded-lg p-6">
<div class="bg-gray-900 rounded p-4">
<h4 class="font-semibold text-yellow-400 mb-2">Example</h4>
<pre class="text-gray-300"><code>use pokeys_lib::*;
fn main() -> Result<()> {`{`}
let mut device = connect_to_device(0)?;
// Configure encoder on pins 10-11 with 4x sampling
let options = EncoderOptions::with_4x_sampling();
device.configure_encoder(0, 10, 11, options)?;
// Monitor encoder position
loop {`{`}
let position = device.get_encoder_value(0)?;
println!(\"Encoder position: {`{`}{`}`}\", position);
std::thread::sleep(std::time::Duration::from_millis(100));
{`}`}
{`}`}</code></pre>
</div>
</div>
</section>
<section class="mb-12">
<h2 class="text-2xl font-bold mb-6 text-white">EncoderOptions — normal encoders</h2>
<div class="bg-gray-800 rounded-lg p-6 mb-4">
<p class="text-gray-300 mb-4">
Options for the 25 normal (per-pin) encoders configured via protocol command <code class="bg-gray-700 px-1 rounded">0x11</code>.
The protocol for normal encoders does <strong>not</strong> expose a direction-invert bit — if you need
to reverse counting direction, swap the channel A/B pins when you call
<code class="bg-gray-700 px-1 rounded">configure_encoder</code>.
</p>
<div class="bg-gray-900 rounded p-4">
<pre class="text-gray-300"><code>pub struct EncoderOptions {`{`}
pub enabled: bool,
pub sampling_4x: bool, // both A and B edges
pub sampling_2x: bool, // only A edges
pub direct_key_mapping_a: bool,
pub macro_mapping_a: bool,
pub direct_key_mapping_b: bool,
pub macro_mapping_b: bool,
{`}`}
impl EncoderOptions {`{`}
pub fn with_4x_sampling() -> Self
pub fn with_2x_sampling() -> Self
pub fn to_byte(&self) -> u8
pub fn from_byte(byte: u8) -> Self
{`}`}</code></pre>
</div>
</div>
</section>
<section class="mb-12">
<h2 class="text-2xl font-bold mb-6 text-white">
FastEncoderOptions — fast encoders (1-3)
<span class="text-xs text-blue-300 bg-blue-900/40 px-2 py-0.5 rounded ml-2 align-middle">since 0.21.9</span>
</h2>
<div class="bg-gray-800 rounded-lg p-6 mb-4">
<p class="text-gray-300 mb-4">
Typed options for the three fast encoders (protocol command <code class="bg-gray-700 px-1 rounded">0xCE</code>).
Bit layout matches the PoLabs <code class="bg-gray-700 px-1 rounded">PoKeysLib</code> C
reference (<code class="bg-gray-700 px-1 rounded">ePK_FastEncoderOptions</code>).
</p>
<div class="bg-gray-900 rounded p-4 mb-4">
<pre class="text-gray-300"><code>pub enum FastEncoderConfiguration {`{`}
Disabled, // 0x00
Config1, // 0x01 — enc1 on pins 1-2, enc2 on 3-4, enc3 on 15-16 (PoKeys55)
Config2, // 0x10 — enc1 on pins 1-2, enc2 on 5-6, enc3 on 15-16 (newer)
{`}`}
pub struct FastEncoderOptions {`{`}
pub disable_4x_sampling: bool, // bit 4 (0x10)
pub invert_direction_1: bool, // bit 5 (0x20)
pub invert_direction_2: bool, // bit 6 (0x40)
pub invert_direction_3: bool, // bit 7 (0x80)
{`}`}</code></pre>
</div>
<div class="bg-gray-900 rounded p-4">
<h4 class="font-semibold text-yellow-400 mb-2">Example</h4>
<pre class="text-gray-300"><code>use pokeys_lib::*;
// Enable fast encoders in Config 2, with encoder 1 direction inverted.
device.configure_fast_encoders(
FastEncoderConfiguration::Config2,
FastEncoderOptions {`{`}
invert_direction_1: true,
..Default::default()
{`}`},
)?;</code></pre>
</div>
</div>
</section>
<section class="mb-12">
<h2 class="text-2xl font-bold mb-6 text-white">
UltraFastEncoderOptions — ultra-fast encoder
<span class="text-xs text-blue-300 bg-blue-900/40 px-2 py-0.5 rounded ml-2 align-middle">since 0.21.9</span>
</h2>
<div class="bg-gray-800 rounded-lg p-6 mb-4">
<p class="text-gray-300 mb-4">
Typed options for the ultra-fast encoder (protocol command <code class="bg-gray-700 px-1 rounded">0x1C</code>,
pins 8/12/13 on PoKeys56E and later). Bit layout per PoKeysLib
<code class="bg-gray-700 px-1 rounded">ePK_UltraFastEncoderOptions</code>.
</p>
<div class="bg-gray-900 rounded p-4 mb-4">
<pre class="text-gray-300"><code>pub struct UltraFastEncoderOptions {`{`}
pub invert_direction: bool, // bit 0 (0x01)
pub signal_mode_direction_clock: bool, // bit 1 (0x02)
pub enable_4x_sampling: bool, // bit 2 (0x04)
{`}`}</code></pre>
</div>
<div class="bg-gray-900 rounded p-4">
<h4 class="font-semibold text-yellow-400 mb-2">Example</h4>
<pre class="text-gray-300"><code>device.configure_ultra_fast_encoder(
/* enable */ true,
UltraFastEncoderOptions {`{`}
invert_direction: true,
enable_4x_sampling: true,
..Default::default()
{`}`},
/* reset_on_index */ false,
/* filter_delay */ 0,
)?;</code></pre>
</div>
</div>
</section>
<section class="mb-12">
<h2 class="text-2xl font-bold mb-4 text-white">Best Practices</h2>
<div class="bg-gray-800 rounded-lg p-6">
<div class="space-y-4">
<div>
<h3 class="text-lg font-semibold mb-2 text-green-400">Sampling Mode Selection</h3>
<ul class="text-gray-300 space-y-1 text-sm">
<li>• Use 4x sampling for maximum precision</li>
<li>• Use 2x sampling for standard applications</li>
<li>• Consider signal quality when choosing mode</li>
</ul>
</div>
<div>
<h3 class="text-lg font-semibold mb-2 text-blue-400">Signal Quality</h3>
<ul class="text-gray-300 space-y-1 text-sm">
<li>• Ensure proper encoder wiring</li>
<li>• Use appropriate pull-up resistors</li>
<li>• Shield encoder cables from noise</li>
</ul>
</div>
</div>
</div>
</section>
</div>
</main>
</div>
</body>
</html>