Crate brickbeam

Expand description

§BRICKBEAM Library

brickbeam is an open source Rust library that enables you to transmit LEGO® Power Functions–style IR signals directly via the kernel’s modern LIRC/rc-core interface. Specifically, it expects a /dev/lircX device (commonly /dev/lirc0) to be available, for example through overlays like gpio-ir-tx or pwm-ir-tx.

The crate implements multiple protocols as separate modules, including Extended, Single Output, Combo Direct, and Combo PWM. Each protocol is self-contained and exposes a remote controller API that encodes commands into the appropriate IR pulse sequence.

§Remote Controllers

brickbeam supports a variety of remote controllers, each designed for a specific type of LEGO® Power Functions command:

• Speed Remote Controller – Ideal for controlling train motors using the Single Output protocol. Configure PWM speeds (with negative values for reverse) or send discrete commands.

• Direct Remote Controller – Uses the Combo Direct protocol, allowing independent control of two outputs (such as setting one motor to “Forward” and the other to “Float”) on a single channel.

• Combo Speed Remote Controller – Leverages the Combo PWM protocol to simultaneously adjust PWM speeds on two outputs.

• Extended Remote Controller – Provides additional control features including braking, toggling speed increments/decrements, and address toggling.

§Usage Example

use brickbeam::{BrickBeam, Channel, Output, SingleOutputCommand, Result};

fn main() -> Result<()> {
    // Initialize the library with the IR transmit device path.
    let brick_beam = BrickBeam::new("/dev/lirc0")?;

    // Create a Speed Remote Controller for a train motor on Channel One using the red output.
    let mut motor = brick_beam.create_speed_remote_controller(Channel::One, Output::RED)?;

    // Set motor speed to 5 (values range from 0 to 7; negative numbers indicate reverse).
    motor.send(SingleOutputCommand::PWM(5))?;

    Ok(())
}

§Requirements

• Linux kernel with LIRC (rc-core) support, ensuring that /dev/lircX is available.

• A properly configured IR transmit overlay on your Raspberry Pi (e.g., gpio-ir-tx or pwm-ir-tx).

See the project’s README for hardware setup instructions.

§Installation

Install prerequisites for building on Bookworm Raspberry Pi

sudo apt-get update
sudo apt-get install wget gnupg software-properties-common
add-apt-repository "deb http://apt.llvm.org/bookworm/ llvm-toolchain-focal-17 main" && sudo apt-get update
sudo apt-get install llvm-17-dev llvm-17-tools libffi-dev

Ensure that export LLVM_SYS_170_PREFIX="/usr/lib/llvm-17" is available for cargo commands.

Add brickbeam as a cargo dependency
```
export LLVM_SYS_170_PREFIX="/usr/lib/llvm-17"
cargo add brickbeam
```
1. If you are building for a native Linux environment and using the IR transmit device at /dev/lirc0 for direct, hardware-accelerated IR signal transmission via the cir library, then use the default dependency configuration. This setting ensures that brickbeam uses dedicated IR hardware dependencies.
  ⓘ
```
[dependencies]
brickbeam = { version = "0.1.0"}
```
2. For platforms such as macOS – where some of the IR hardware dependencies (used by the default “cir” feature) may not compile – you can build using only the emulator. To do so, disable the default features and enable the emulator feature as follows:
  ⓘ
```
[dependencies]
brickbeam = { version = "0.1.0", default-features = false}
```
  NOTE: Use the IR transmission emulator for development only (e.g., on macOS). Do not use default-features = false in production! In production, the cir feature must be enabled (this is the default setting).

For more complete examples, see the examples directory.

Disclaimer: This project is not sponsored, authorized, or endorsed by the LEGO Group. “LEGO”® is a trademark of the LEGO Group. LEGO® and Power Functions™ are trademarks of the LEGO Group.

The IRP protocols and data structures in this crate are re-expressions of publicly available timing information for LEGO® Power Functions signals. They are not copied verbatim from any confidential or proprietary document.

Acknowledgements: Special thanks to my brother for his unwavering support throughout this project.

Structs§

BrickBeam: The primary API for creating various remote controllers for LEGO IR transmission.
ComboDirectCommand: Represents a Combo Direct command used to control two outputs simultaneously via the Combo Direct protocol.
ComboPwmCommand: Represents a Combo PWM command used for simultaneous control of two outputs via the Combo PWM protocol.
ComboSpeedRemoteController: ComboSpeedRemoteController is a struct that represents a remote controller for the LEGO® Power Functions Speed IR Remote Control 8879.
DirectRemoteController: DirectRemoteController is a struct that represents a remote controller for the LEGO® Power Functions IR Remote Control 8885.
ExtendedRemoteController: ExtendedRemoteController
SpeedRemoteController: SpeedRemoteController is a struct that represents a remote controller for the LEGO® Power Functions Speed IR Remote Control 8879.

Enums§

Channel
DirectState
Error: Possible errors while encoding commands or transmitting pulses.
ExtendedCommand: Represents an extended command for the Extended protocol.
Output
SingleOutputCommand: This enum represents the commands that can be sent to a controller using the Single Output protocol. Commands can either be specified as a PWM (Pulse Width Modulation) value, which sets the speed and direction of a motor, or as a discrete command that triggers a predefined operation (such as toggling direction).
SingleOutputDiscrete

Traits§

PulseTransmitter: On non–Linux platforms, the send_pulses functions simply print the encoded pulse sequence, acting as a development/testing emulator. The library abstracts the underlying hardware differences by using the DefaultPulseTransmitter:

Type Aliases§

DefaultPulseTransmitter: Default PulseTransmitter implementation. On Linux, this is the actual IR transmitter; on other platforms, it is simulated.
Result: The library’s specialized Result type.

Crate brickbeamCopy item path