# bpod_core.bpod.structs

Data structures used by the bpod module.

## Classes

### *class* bpod_core.bpod.structs.BpodInfo

Bases: [`Struct`](https://msgspec.dev/api.html#msgspec.Struct)

Information about a specific Bpod device.

#### location *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

User-defined location of the device.

#### name *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

User-defined name of the device.

#### port *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)*

Port on which the device is connected.

#### serial_number *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

Serial number of the device.

#### zmq_pub *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)*

ZeroMQ PUB service address.

#### zmq_rep *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)*

ZeroMQ REP service address.

### *class* bpod_core.bpod.structs.BpodMessage

Bases: [`Struct`](https://msgspec.dev/api.html#msgspec.Struct)

Base class for all messages exchanged between ServiceHost and ServiceClient.

### *class* bpod_core.bpod.structs.BpodSettings

Bases: [`Struct`](https://msgspec.dev/api.html#msgspec.Struct)

Settings for a specific Bpod device.

#### location *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

User-defined location of the device.

#### name *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

User-defined name of the device.

#### serial_number *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

Serial number of the device.

#### zmq_port_pub *: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None)*

Port number for the ZeroMQ PUB service.

#### zmq_port_rep *: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None)*

Port number for the ZeroMQ REP service.

### *class* bpod_core.bpod.structs.EventInput

Bases: [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage)

Message for a single input event.

#### channel *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)*

Name of the input channel, or `None` for synthetic events.

#### event *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

Name of the input event.

#### time_us *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Absolute time of the event (microseconds since epoch, UTC).

#### value *: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None)*

The event's value, or `None` if not applicable.

### *class* bpod_core.bpod.structs.EventOutput

Bases: [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage)

Message for a single output action.

#### channel *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

Name of the output channel.

#### time_us *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Absolute time of the action (microseconds since epoch, UTC).

#### value *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The value set on the output channel.

### *class* bpod_core.bpod.structs.EventStateEnd

Bases: [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage)

Message marking the end of a state.

#### state *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

Name of the state.

#### time_us *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Absolute time of the event (microseconds since epoch, UTC).

### *class* bpod_core.bpod.structs.EventStateStart

Bases: [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage)

Message marking the start of a state.

#### state *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

Name of the state.

#### time_us *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Absolute time of the event (microseconds since epoch, UTC).

### *class* bpod_core.bpod.structs.EventTrialEnd

Bases: [`BpodMessage`](#bpod_core.bpod.structs.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`](#bpod_core.bpod.structs.EventTrialEnd) nor
[`EventTrialEndControl`](#bpod_core.bpod.structs.EventTrialEndControl) - its stream simply ends. See
[`EventTrialStart`](#bpod_core.bpod.structs.EventTrialStart) for the ordering semantics.

#### time_us *: [int](https://docs.python.org/3/builtins/functions.html#int)*

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

#### trial *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Zero-based trial index.

### *class* bpod_core.bpod.structs.EventTrialEndControl

Bases: [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage)

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

Trails [`EventTrialEnd`](#bpod_core.bpod.structs.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](https://docs.python.org/3/builtins/functions.html#int)*

Total number of messages published for the trial (completeness check).

#### time_us *: [int](https://docs.python.org/3/builtins/functions.html#int)*

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

#### trial *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Zero-based trial index.

### *class* bpod_core.bpod.structs.EventTrialStart

Bases: [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage)

Message marking the start of a trial.

Trial streams are strictly sequential: all messages between an
[`EventTrialStart`](#bpod_core.bpod.structs.EventTrialStart) and the next [`EventTrialEnd`](#bpod_core.bpod.structs.EventTrialEnd) belong to the
trial identified by these markers, and a clean trial's stream is terminated
by a trailing [`EventTrialEndControl`](#bpod_core.bpod.structs.EventTrialEndControl).

#### fsm_hash *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

Hex digest of the state machine's hash.

#### time_us *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Absolute time of the trial start (microseconds since epoch, UTC).

#### trial *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Zero-based trial index.

### *class* bpod_core.bpod.structs.HardwareConfiguration

Bases: [`Struct`](https://msgspec.dev/api.html#msgspec.Struct)

Represents the Bpod's on-board hardware configuration.

#### cycle_frequency *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Frequency of the state machine's refresh cycle during a trial in Hertz.

#### cycle_period_us *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Period of the state machine's refresh cycle during a trial in microseconds.

#### input_description *: [bytes](https://docs.python.org/3/builtins/stdtypes.html#bytes)*

Array indicating the state machine's onboard input channel types.

#### max_bytes_per_serial_message *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Maximum number of bytes allowed per serial message.

#### max_serial_events *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Maximum number of behavior events allocatable among connected modules.

#### max_states *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Maximum number of supported states in a single state machine description.

#### n_conditions *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Number of condition-events supported.

#### n_global_counters *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Number of global counters supported.

#### n_global_timers *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Number of global timers supported.

#### n_inputs *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Number of input channels.

#### n_modules *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Number of modules supported by the state machine.

#### n_outputs *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Number of channels in the state machine's output channel description array.

#### output_description *: [bytes](https://docs.python.org/3/builtins/stdtypes.html#bytes)*

Array indicating the state machine's onboard output channel types.

### *class* bpod_core.bpod.structs.HardwareState

Bases: [`Struct`](https://msgspec.dev/api.html#msgspec.Struct)

Represents the Bpod's current hardware state.

#### status_led *: [bool](https://docs.python.org/3/builtins/functions.html#bool) | [None](https://docs.python.org/3/builtins/constants.html#None)*

The current state of the Bpod's status LED. None if unknown.

### *class* bpod_core.bpod.structs.RawEvent

Bases: [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)

Raw event data from the Bpod device.

#### event_id *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Index of the event.

#### micros_us *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Time of the event relative to the Bpod's session clock (microseconds).

### *class* bpod_core.bpod.structs.RawSoftcode

Bases: [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)

Raw softcode data from the Bpod device.

#### micros_us *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Bpod session clock at the time of softcode firing (microseconds).

#### received_ns *: [int](https://docs.python.org/3/builtins/functions.html#int)*

`time.perf_counter_ns()` captured immediately after the serial read.

#### softcode *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Zero-based softcode value.

### *class* bpod_core.bpod.structs.ReplyGeneric

Bases: [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage)

Envelope for a generic reply.

#### value *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)*

The content of the reply.

### *class* bpod_core.bpod.structs.ReplyWelcome

Bases: [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage)

Envelope for a handshake reply.

#### location *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)*

The Bpod's user-defined location.

#### name *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)*

The Bpod's user-defined name.

#### serial_number *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

The Bpod's unique serial number.

#### version *: [VersionInfo](#bpod_core.bpod.structs.VersionInfo)*

Version information of the Bpod's firmware and hardware.

### *class* bpod_core.bpod.structs.RequestBye

Bases: [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage)

Envelope for a disconnect notice.

### *class* bpod_core.bpod.structs.RequestCall

Bases: [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage)

Envelope for a method call request.

#### args *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)*

The arguments to be passed to the method.

#### kwargs *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]*

Keyword arguments to be passed to the method.

#### method_name *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

The name of the method to be called.

### *class* bpod_core.bpod.structs.RequestData

Bases: [`RequestCall`](#bpod_core.bpod.structs.RequestCall)

Envelope for a data request.

#### compression *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['uncompressed', 'lz4', 'zstd']*

The compression method to be used for the data.

### *class* bpod_core.bpod.structs.RequestHello

Bases: [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage)

Envelope for a handshake request.

#### bpod_core_version *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

The version of bpod-core that the client is using.

### *class* bpod_core.bpod.structs.StateMachineLookup

Bases: [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)

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

#### fsm_hash *: [bytes](https://docs.python.org/3/builtins/stdtypes.html#bytes)*

The state machine's hash value.

#### state_actions *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [int](https://docs.python.org/3/builtins/functions.html#int)]]*

Per-state mapping of action name to value.

#### state_lookup *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[int](https://docs.python.org/3/builtins/functions.html#int), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]*

Mapping from state index to state name.

#### state_names *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]*

Names of all states, indexed by state index.

#### state_transition_matrix *: [NDArray](https://numpy.org/doc/stable/reference/typing.html#numpy.typing.NDArray)[[uint8](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.uint8)]*

Transition matrix of shape `(n_states, 255)`.

#### use_back_op *: [bool](https://docs.python.org/3/builtins/functions.html#bool)*

Whether the `>back` operator is used.

### *class* bpod_core.bpod.structs.TimeReferences

Bases: [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)

Reference values for performance counters.

#### init_perf_counter_ns *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Performance counter at class initialization (nanoseconds).

#### init_system_time_ns *: [int](https://docs.python.org/3/builtins/functions.html#int)*

System time at class initialization (nanoseconds relative to epoch).

#### reset_system_time_ns *: [int](https://docs.python.org/3/builtins/functions.html#int)*

System time when Bpod's session clock was last reset (nanoseconds).

### *class* bpod_core.bpod.structs.VersionInfo

Bases: [`Struct`](https://msgspec.dev/api.html#msgspec.Struct)

Data structure representing various version information.

#### bpod_core *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

bpod-core version

#### firmware *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[int](https://docs.python.org/3/builtins/functions.html#int), [int](https://docs.python.org/3/builtins/functions.html#int)]*

Firmware version (major, minor)

#### machine *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Machine type (numerical)

#### machine_str *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

Machine type (string)

#### pcb *: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None)*

PCB revision, if applicable

## Attributes

### bpod_core.bpod.structs.BpodEventType

Vocabulary of the trial DataFrame's `type` column.

alias of [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)['TrialStart', 'TrialEnd', 'TrialEndControl', 'StateStart', 'StateEnd', 'InputEvent', 'OutputAction']

### bpod_core.bpod.structs.BpodReplyUnion *: [TypeAlias](https://docs.python.org/3/library/typing.html#typing.TypeAlias)* *= bpod_core.bpod.structs.ReplyGeneric | bpod_core.bpod.structs.ReplyWelcome*

Tagged union of all concrete [`BpodMessage`](#bpod_core.bpod.structs.BpodMessage) subclasses used for replies.

### bpod_core.bpod.structs.BpodRequestUnion *: [TypeAlias](https://docs.python.org/3/library/typing.html#typing.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`](#bpod_core.bpod.structs.BpodMessage) subclasses used for requests.

### bpod_core.bpod.structs.BpodEventUnion *: [TypeAlias](https://docs.python.org/3/library/typing.html#typing.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`](#bpod_core.bpod.structs.BpodMessage) subclasses used for events.