bpod_core.bpod.structs#

Data structures used by the bpod module.

Classes#

class bpod_core.bpod.structs.BpodInfo #

Bases: Struct

Information about a specific Bpod device.

location: str#: User-defined location of the device.

name: str#: User-defined name of the device.

port: str | None#: Port on which the device is connected.

serial_number: str#: Serial number of the device.

zmq_pub: str | None#: ZeroMQ PUB service address.

zmq_rep: str | None#: ZeroMQ REP service address.

class bpod_core.bpod.structs.BpodMessage #

Bases: Struct

Base class for all messages exchanged between ServiceHost and ServiceClient.

class bpod_core.bpod.structs.BpodSettings #

Bases: Struct

Settings for a specific Bpod device.

location: str#: User-defined location of the device.

name: str#: User-defined name of the device.

serial_number: str#: Serial number of the device.

zmq_port_pub: int | None#: Port number for the ZeroMQ PUB service.

zmq_port_rep: int | None#: Port number for the ZeroMQ REP service.

class bpod_core.bpod.structs.EventInput #

Bases: BpodMessage

Message for a single input event.

channel: str | None#: Name of the input channel, or None for synthetic events.

event: str#: Name of the input event.

time_us: int#: Absolute time of the event (microseconds since epoch, UTC).

value: int | None#: The event’s value, or None if not applicable.

class bpod_core.bpod.structs.EventOutput #

Bases: BpodMessage

Message for a single output action.

channel: str#: Name of the output channel.

time_us: int#: Absolute time of the action (microseconds since epoch, UTC).

value: int#: The value set on the output channel.

class bpod_core.bpod.structs.EventStateEnd #

Bases: BpodMessage

Message marking the end of a state.

state: str#: Name of the state.

time_us: int#: Absolute time of the event (microseconds since epoch, UTC).

class bpod_core.bpod.structs.EventStateStart #

Bases: BpodMessage

Message marking the start of a state.

state: str#: Name of the state.

time_us: int#: Absolute time of the event (microseconds since epoch, UTC).

class bpod_core.bpod.structs.EventTrialEnd #

Bases: BpodMessage

Message marking the end of a trial.

Only published when the hardware exit packet is received: a trial aborted without one publishes neither EventTrialEnd nor EventTrialEndControl - its stream simply ends. See EventTrialStart for the ordering semantics.

time_us: int#: Absolute time of the trial end, derived from the hardware cycle count (microseconds since epoch, UTC).

trial: int#: Zero-based trial index.

class bpod_core.bpod.structs.EventTrialEndControl #

Bases: BpodMessage

Message terminating a trial’s stream with timing-verification data.

Trails EventTrialEnd and carries the hardware’s independent end-of-trial microsecond count - the same clock pair compared by the reader’s timing-violation warning.

n_events: int#: Total number of messages published for the trial (completeness check).

time_us: int#: Hardware microsecond count at the end of the trial (microseconds since epoch, UTC).

trial: int#: Zero-based trial index.

class bpod_core.bpod.structs.EventTrialStart #

Bases: BpodMessage

Message marking the start of a trial.

Trial streams are strictly sequential: all messages between an EventTrialStart and the next EventTrialEnd belong to the trial identified by these markers, and a clean trial’s stream is terminated by a trailing EventTrialEndControl.

fsm_hash: str#: Hex digest of the state machine’s hash.

time_us: int#: Absolute time of the trial start (microseconds since epoch, UTC).

trial: int#: Zero-based trial index.

class bpod_core.bpod.structs.HardwareConfiguration #

Bases: Struct

Represents the Bpod’s on-board hardware configuration.

cycle_frequency: int#: Frequency of the state machine’s refresh cycle during a trial in Hertz.

cycle_period_us: int#: Period of the state machine’s refresh cycle during a trial in microseconds.

input_description: bytes#: Array indicating the state machine’s onboard input channel types.

max_bytes_per_serial_message: int#: Maximum number of bytes allowed per serial message.

max_serial_events: int#: Maximum number of behavior events allocatable among connected modules.

max_states: int#: Maximum number of supported states in a single state machine description.

n_conditions: int#: Number of condition-events supported.

n_global_counters: int#: Number of global counters supported.

n_global_timers: int#: Number of global timers supported.

n_inputs: int#: Number of input channels.

n_modules: int#: Number of modules supported by the state machine.

n_outputs: int#: Number of channels in the state machine’s output channel description array.

output_description: bytes#: Array indicating the state machine’s onboard output channel types.

class bpod_core.bpod.structs.HardwareState #

Bases: Struct

Represents the Bpod’s current hardware state.

status_led: bool | None#: The current state of the Bpod’s status LED. None if unknown.

class bpod_core.bpod.structs.RawEvent #

Bases: NamedTuple

Raw event data from the Bpod device.

event_id: int#: Index of the event.

micros_us: int#: Time of the event relative to the Bpod’s session clock (microseconds).

class bpod_core.bpod.structs.RawSoftcode #

Bases: NamedTuple

Raw softcode data from the Bpod device.

micros_us: int#: Bpod session clock at the time of softcode firing (microseconds).

received_ns: int#: time.perf_counter_ns() captured immediately after the serial read.

softcode: int#: Zero-based softcode value.

class bpod_core.bpod.structs.ReplyGeneric #

Bases: BpodMessage

Envelope for a generic reply.

value: Any#: The content of the reply.

class bpod_core.bpod.structs.ReplyWelcome #

Bases: BpodMessage

Envelope for a handshake reply.

location: str | None#: The Bpod’s user-defined location.

name: str | None#: The Bpod’s user-defined name.

serial_number: str#: The Bpod’s unique serial number.

version: VersionInfo#: Version information of the Bpod’s firmware and hardware.

class bpod_core.bpod.structs.RequestBye #

Bases: BpodMessage

Envelope for a disconnect notice.

class bpod_core.bpod.structs.RequestCall #

Bases: BpodMessage

Envelope for a method call request.

args: tuple#: The arguments to be passed to the method.

kwargs: dict[str, Any]#: Keyword arguments to be passed to the method.

method_name: str#: The name of the method to be called.

class bpod_core.bpod.structs.RequestData #

Bases: RequestCall

Envelope for a data request.

compression: Literal['uncompressed', 'lz4', 'zstd']#: The compression method to be used for the data.

class bpod_core.bpod.structs.RequestHello #

Bases: BpodMessage

Envelope for a handshake request.

bpod_core_version: str#: The version of bpod-core that the client is using.

class bpod_core.bpod.structs.StateMachineLookup #

Bases: NamedTuple

Lookup data to decode the raw event stream during a state machine trial.

fsm_hash: bytes#: The state machine’s hash value.

state_actions: list[dict[str, int]]#: Per-state mapping of action name to value.

state_lookup: dict[int, str]#: Mapping from state index to state name.

state_names: list[str]#: Names of all states, indexed by state index.

state_transition_matrix: NDArray[uint8]#: Transition matrix of shape (n_states, 255).

use_back_op: bool#: Whether the >back operator is used.

class bpod_core.bpod.structs.TimeReferences #

Bases: NamedTuple

Reference values for performance counters.

init_perf_counter_ns: int#: Performance counter at class initialization (nanoseconds).

init_system_time_ns: int#: System time at class initialization (nanoseconds relative to epoch).

reset_system_time_ns: int#: System time when Bpod’s session clock was last reset (nanoseconds).

class bpod_core.bpod.structs.VersionInfo #

Bases: Struct

Data structure representing various version information.

bpod_core: str#: bpod-core version

firmware: tuple[int, int]#: Firmware version (major, minor)

machine: int#: Machine type (numerical)

machine_str: str#: Machine type (string)

pcb: int | None#: PCB revision, if applicable

Attributes#

bpod_core.bpod.structs.BpodEventType#

Vocabulary of the trial DataFrame’s type column.

alias of Literal[‘TrialStart’, ‘TrialEnd’, ‘TrialEndControl’, ‘StateStart’, ‘StateEnd’, ‘InputEvent’, ‘OutputAction’]

bpod_core.bpod.structs.BpodReplyUnion: TypeAlias = bpod_core.bpod.structs.ReplyGeneric | bpod_core.bpod.structs.ReplyWelcome#: Tagged union of all concrete BpodMessage subclasses used for replies.

bpod_core.bpod.structs.BpodRequestUnion: TypeAlias = bpod_core.bpod.structs.RequestHello | bpod_core.bpod.structs.RequestBye | bpod_core.bpod.structs.RequestCall | bpod_core.bpod.structs.RequestData#: Tagged union of all concrete BpodMessage subclasses used for requests.

bpod_core.bpod.structs.BpodEventUnion: TypeAlias = bpod_core.bpod.structs.EventTrialStart | bpod_core.bpod.structs.EventStateStart | bpod_core.bpod.structs.EventStateEnd | bpod_core.bpod.structs.EventInput | bpod_core.bpod.structs.EventOutput | bpod_core.bpod.structs.EventTrialEnd | bpod_core.bpod.structs.EventTrialEndControl#: Tagged union of all concrete BpodMessage subclasses used for events.