Word

busylight_core.word

Bitwise operations on a word of bits.

Classes

busylight_core.word.Word

Word(value=0, length=8)

Binary data structure for device state management with BitField support.

Provides bit-level manipulation of binary data with named field access through BitField descriptors. Use this as a base class for device state objects that need to pack/unpack complex binary protocols into structured, named fields.

Create a Word instance for binary data manipulation.

Initializes a binary word with the specified bit length and initial value. The length must be a multiple of 8 to align with byte boundaries. Use this to create state objects for devices that use binary communication protocols.

:param value: Initial integer value to store in the word :param length: Total bit length, must be multiple of 8 :raises ValueError: If length is not a positive multiple of 8

Source code in src/busylight_core/word.py

def __init__(self, value: int = 0, length: int = 8) -> None:
    """Create a Word instance for binary data manipulation.

    Initializes a binary word with the specified bit length and initial value.
    The length must be a multiple of 8 to align with byte boundaries. Use this
    to create state objects for devices that use binary communication protocols.


    :param value: Initial integer value to store in the word
    :param length: Total bit length, must be multiple of 8
    :raises ValueError: If length is not a positive multiple of 8
    """
    if length <= 0 or length % 8 != 0:
        msg = "length must be a multiple of 8"
        raise ValueError(msg)

    self.initial_value = value
    self.length = length
    self.bits = array.array("B", [(value >> n) & 1 for n in self.range])

Attributes

busylight_core.word.Word.initial_value instance-attribute

initial_value = value

busylight_core.word.Word.length instance-attribute

length = length

busylight_core.word.Word.bits instance-attribute

bits = array('B', [value >> n & 1 for n in range])

busylight_core.word.Word.value property

value

Return the integer value of the word.

busylight_core.word.Word.range property

range

Return the range of bit offsets for this word.

busylight_core.word.Word.hex property

hex

Return a string hexadecimal representation of the word.

busylight_core.word.Word.bin property

bin

Return a string binary representation of the word.

Functions

busylight_core.word.Word.clear

clear()

Clear all bits in the word.

Source code in src/busylight_core/word.py

def clear(self) -> None:
    """Clear all bits in the word."""
    self.bits = array.array("B", [0] * self.length)

busylight_core.word.ReadOnlyBitField

ReadOnlyBitField(offset, width=1)

Descriptor for read-only named bit fields within Word instances.

Creates a named field that provides read-only access to specific bit ranges within a Word. Use this for device state fields that should not be modified by user code, such as status indicators or hardware-controlled values.

Create a read-only bit field descriptor.

Defines a named field that maps to specific bit positions within a Word. The field will be accessible as a regular attribute on Word instances but will raise AttributeError on assignment attempts.

:param offset: Starting bit position within the word (0-based from LSB) :param width: Number of consecutive bits to include in the field

Source code in src/busylight_core/word.py

def __init__(self, offset: int, width: int = 1) -> None:
    """Create a read-only bit field descriptor.

    Defines a named field that maps to specific bit positions within a Word.
    The field will be accessible as a regular attribute on Word instances
    but will raise AttributeError on assignment attempts.


    :param offset: Starting bit position within the word (0-based from LSB)
    :param width: Number of consecutive bits to include in the field
    """
    self.field = slice(offset, offset + width)
    self.offset = offset  # Store for introspection
    self.width = width  # Store for introspection

Attributes

busylight_core.word.ReadOnlyBitField.field instance-attribute

field = slice(offset, offset + width)

busylight_core.word.ReadOnlyBitField.offset instance-attribute

offset = offset

busylight_core.word.ReadOnlyBitField.width instance-attribute

width = width

busylight_core.word.BitField

BitField(offset, width=1)

Bases: ReadOnlyBitField

Descriptor for mutable named bit fields within Word instances.

Creates a named field that provides read/write access to specific bit ranges within a Word. Use this for device control fields that can be modified by user code, such as color values, effect settings, or device configuration.

Create a read-only bit field descriptor.

Defines a named field that maps to specific bit positions within a Word. The field will be accessible as a regular attribute on Word instances but will raise AttributeError on assignment attempts.

:param offset: Starting bit position within the word (0-based from LSB) :param width: Number of consecutive bits to include in the field

Source code in src/busylight_core/word.py

def __init__(self, offset: int, width: int = 1) -> None:
    """Create a read-only bit field descriptor.

    Defines a named field that maps to specific bit positions within a Word.
    The field will be accessible as a regular attribute on Word instances
    but will raise AttributeError on assignment attempts.


    :param offset: Starting bit position within the word (0-based from LSB)
    :param width: Number of consecutive bits to include in the field
    """
    self.field = slice(offset, offset + width)
    self.offset = offset  # Store for introspection
    self.width = width  # Store for introspection

Attributes

busylight_core.word.BitField.field instance-attribute

field = slice(offset, offset + width)

busylight_core.word.BitField.offset instance-attribute

offset = offset

busylight_core.word.BitField.width instance-attribute

width = width