lib8tion 0.1.1

Rust port of FastLED lib8tion — fast 8-bit math primitives for embedded LED programming
Documentation
  • Coverage
  • 99.3%
    141 out of 142 items documented2 out of 126 items with examples
  • Size
  • Source code size: 126.6 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 2.5 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 9s Average build duration of successful builds.
  • all releases: 6s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • orhanbalci/lib8tion
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • orhanbalci

lib8tion

Fast 8-/16-bit fixed-point math for no_std embedded targets — a Rust port of the math primitives from FastLED's lib8tion.

[dependencies]
lib8tion = "0.1"

#![no_std], #![forbid(unsafe_code)], no allocation, no panics. Every function is pure integer math with overflow behavior chosen to match the original C implementation (saturating, wrapping, or truncating — whichever FastLED's algorithm relies on), so animations ported from FastLED/Arduino sketches produce identical output.

Why

LED animation code leans on cheap, branch-light integer math: scale a byte by a fraction, blend two colors, approximate a sine wave, oscillate a value at a given BPM. FastLED's lib8tion is the reference implementation of these tricks for AVR/ARM microcontrollers; this crate brings the same primitives — and the same bit-for-bit behavior — to no_std Rust.

What's here

Module Contents
math8 Saturating/wrapping byte arithmetic: qadd8, qsub8, add8, avg8, mul8, qmul8, abs8, blend8 (+ _8bit/_16bit/_8bit_full_range variants), mod8, sqrt8/sqrt16, ...
scale8 Fast scaling & dimming: scale8, scale8_video, scale16, nscale8x3/nscale8 (in place, incl. whole-slice), dim8_* / brighten8_*
trig8 Lookup-table approximations of sin/cos: sin8, cos8, sin16, cos16
lerp Linear interpolation & range mapping: lerp8by8, lerp16by8, lerp16by16, lerp15by8, lerp15by16, map8
ease Easing curves & waveform generators: ease8_in_out_quad/cubic/approx, ease16_in_out_quad/cubic, triwave8, quadwave8, cubicwave8, squarewave8
beat BPM-driven phase/value oscillators: beat8, beat16, beat88, beatsin8, beatsin16, beatsin88
intmap Generic integer range remapping between bit widths: int_scale
fixed_point Qfx<F> fixed-point scale-factor type (Q44, Q62, Q88, Q124)
random Rng16 — a small, fast, explicitly-seeded PRNG (not cryptographically secure)

All of the above are re-exported from the crate root, so lib8tion::scale8, lib8tion::sin8, lib8tion::beat8, etc. all work directly.

Design notes

  • No hidden global state. FastLED's C functions read implicit global state — millis() for the beat generators, a static seed for random8(). This port instead takes that state as an explicit argument (now_millis: u32 for beat8 & friends, an explicit seed for Rng16) — the only sensible shape in no_std, where there's no universal monotonic clock or global allocator to reach for. Drive the beat generators with whatever millisecond counter your platform provides (SysTick, an RTC, a simulation clock, ...).
  • Overflow semantics match the C original on purpose. Where FastLED relies on u8/u16 truncation, signed wraparound, or 32-bit overflow in an intermediate product, this port reproduces it exactly (via wrapping_*/explicit casts) rather than "fixing" it — these functions are used as building blocks in animations that depend on the exact periodic behavior.
  • const fn wherever possible. Most functions are const fn, so lookup tables, color palettes, and animation parameters can be computed at compile time.

Verifying against FastLED

This isn't just "should behave like FastLED" — it's checked against FastLED's actual C reference code on every test run:

  • fastled-ref/ is a small helper crate that compiles a faithful C transcription of FastLED's portable reference algorithms (shim.c, built via the cc crate) and exposes them through extern "C" bindings. It's a [dev-dependencies]-only path dependency, so its unsafe FFI code never enters lib8tion itself — #![forbid(unsafe_code)] stays intact.
  • tests/differential.rs exhaustively (for u8 domains) or densely (for wider domains) asserts that every ported function in lib8tion produces bit-for-bit identical output to FastLED's C code.
  • tests/properties.rs adds proptest-driven property tests: randomized differential checks (with shrinking, for the domains too wide to sweep exhaustively) plus algebraic invariants the Rust port must satisfy on its own (saturation bounds, range bounds, identities at fixed points).
cargo test

(fastled-ref is a path-only dev-dependency and isn't published — cargo test needs a git clone of this repo, not the crates.io source tarball.)

no_std / embedded

The crate has zero dependencies and builds for bare-metal targets:

cargo build --target thumbv7em-none-eabihf --release

License

MIT