schema

package
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 1, 2025 License: ISC Imports: 6 Imported by: 0

Documentation

Overview

Package schema contains the Buttplug message schema for version 4.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsInternalMessage

func IsInternalMessage(m Message) bool

IsInternalMessage returns whether the message is an internal-only message.

Types

type ClientID

type ClientID int

ClientID: user-set id for the message. 0 denotes system message and is reserved.

type ClientMessage

type ClientMessage interface {
	Message
	// ClientID returns the ID field of the message.
	ClientID() ClientID
	// WithID sets the ID field of the shallow-copied message and returns the modified message.
	WithID(id ClientID) ClientMessage
	// contains filtered or unexported methods
}

ClientMessage represents a message that can be sent from the client to the server. It extends Message with a way to set the client ID to be used when sending the message.

The following messages are defined:

type DeviceFeature

type DeviceFeature struct {
	FeatureDescription string                            `json:"FeatureDescription"`
	FeatureIndex       int                               `json:"FeatureIndex"`
	Input              ptr.Optional[DeviceFeatureInput]  `json:"Input,omitzero"`
	Output             ptr.Optional[DeviceFeatureOutput] `json:"Output,omitzero"`
}

DeviceFeature: specifies feature for a device.

type DeviceFeatureInput

type DeviceFeatureInput map[string]DeviceFeatureInputValue

DeviceFeatureInput: properties map for DeviceFeature.Input.

type DeviceFeatureInputValue

type DeviceFeatureInputValue struct {
	ValueRange [][]int `json:"ValueRange"`
}

DeviceFeatureInputValue: This is the properties map type for DeviceFeatureInput.

type DeviceFeatureOutput

DeviceFeatureOutput: properties map for DeviceFeature.Output.

type DeviceFeatureOutputKey

type DeviceFeatureOutputKey string

DeviceFeatureOutputKey represents valid keys in DeviceFeatureOutput.

const (
	DeviceFeatureOutputPositionWithDuration DeviceFeatureOutputKey = "PositionWithDuration"
	DeviceFeatureOutputVibrate              DeviceFeatureOutputKey = "Vibrate"
	DeviceFeatureOutputRotate               DeviceFeatureOutputKey = "Rotate"
	DeviceFeatureOutputOscillate            DeviceFeatureOutputKey = "Oscillate"
	DeviceFeatureOutputConstrict            DeviceFeatureOutputKey = "Constrict"
	DeviceFeatureOutputSpray                DeviceFeatureOutputKey = "Spray"
	DeviceFeatureOutputPosition             DeviceFeatureOutputKey = "Position"
	DeviceFeatureOutputTemperature          DeviceFeatureOutputKey = "Temperature"
	DeviceFeatureOutputLED                  DeviceFeatureOutputKey = "Led"
)

Constants for valid keys in DeviceFeatureOutput.

type DeviceFeatureOutputPositionWithDurationValue

type DeviceFeatureOutputPositionWithDurationValue struct {
	// Position: serialization of Rust's RangeInclusive Type.
	Position RangeInclusive `json:"Position"`
	// Duration: serialization of Rust's RangeInclusive Type.
	Duration RangeInclusive `json:"Duration"`
}

DeviceFeatureOutputPositionWithDurationValue is the value matching pattern for DeviceFeatureOutputPositionWithDuration of DeviceFeatureOutput.

type DeviceFeatureOutputValue

type DeviceFeatureOutputValue struct {
	// Value: serialization of Rust's RangeInclusive Type.
	Value RangeInclusive `json:"Value"`
}

DeviceFeatureOutputValue is the value matching pattern for DeviceFeatureOutputVibrate, DeviceFeatureOutputRotate, DeviceFeatureOutputOscillate, DeviceFeatureOutputConstrict, DeviceFeatureOutputSpray, DeviceFeatureOutputPosition, DeviceFeatureOutputTemperature and DeviceFeatureOutputLED of DeviceFeatureOutput.

type DeviceFeatureOutputValueType

type DeviceFeatureOutputValueType interface {
	// contains filtered or unexported methods
}

DeviceFeatureOutputValueType is a type that represents possible values of the map DeviceFeatureOutput.

The following types can be used for this interface:

type DeviceIndex

type DeviceIndex int

DeviceIndex: index used for referencing the device in device messages.

type DeviceListDevices added in v0.0.6

type DeviceListDevices map[int]DeviceListDevicesValue

Devices: array of device ids and names.

type DeviceListDevicesValue added in v0.0.6

type DeviceListDevicesValue struct {
	// DeviceName: name of the device.
	DeviceName DeviceName `json:"DeviceName"`
	// DeviceIndex: index used for referencing the device in device messages.
	DeviceIndex            DeviceIndex                          `json:"DeviceIndex"`
	DeviceMessageTimingGap int                                  `json:"DeviceMessageTimingGap"`
	DeviceFeatures         DeviceListDevicesValueDeviceFeatures `json:"DeviceFeatures"`
	DeviceDisplayName      ptr.Optional[string]                 `json:"DeviceDisplayName,omitzero"`
}

DeviceListDevicesValue: This is the properties map type for DeviceListDevices.

type DeviceListDevicesValueDeviceFeatures added in v0.0.6

type DeviceListDevicesValueDeviceFeatures map[int]DeviceFeature

DeviceListDevicesValueDeviceFeatures: properties map for DeviceListDevicesValue.DeviceFeatures.

type DeviceListMessage

type DeviceListMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ServerID `json:"Id"`
	// Devices: array of device ids and names.
	Devices DeviceListDevices `json:"Devices"`
}

DeviceListMessage: list of all available devices known to the system.

func (*DeviceListMessage) LogValue

func (d *DeviceListMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*DeviceListMessage) ServerID

func (d *DeviceListMessage) ServerID() ServerID

ServerID implements ServerMessage

func (*DeviceListMessage) Type

func (d *DeviceListMessage) Type() MessageType

Type returns MessageTypeDeviceList.

type DeviceName

type DeviceName string

DeviceName: name of the device.

type ErrorMessage

type ErrorMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID           ServerID `json:"Id"`
	ErrorMessage string   `json:"ErrorMessage"`
	ErrorCode    float64  `json:"ErrorCode"`
}

ErrorMessage: signifies the server encountered an error while processing the message indicated by the id.

func (*ErrorMessage) LogValue

func (e *ErrorMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*ErrorMessage) ServerID

func (e *ErrorMessage) ServerID() ServerID

ServerID implements ServerMessage

func (*ErrorMessage) Type

func (e *ErrorMessage) Type() MessageType

Type returns MessageTypeError.

type InputCmdMessage

type InputCmdMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ClientID `json:"Id"`
	// DeviceIndex: index used for referencing the device in device messages.
	DeviceIndex  DeviceIndex `json:"DeviceIndex"`
	FeatureIndex int         `json:"FeatureIndex"`
	InputType    string      `json:"InputType"`
	InputCommand string      `json:"InputCommand"`
}

InputCmdMessage: sends a request to read a sensor value.

func (*InputCmdMessage) ClientID

func (i *InputCmdMessage) ClientID() ClientID

ClientID implements ClientMessage

func (*InputCmdMessage) LogValue

func (i *InputCmdMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*InputCmdMessage) Type

func (i *InputCmdMessage) Type() MessageType

Type returns MessageTypeInputCmd.

func (*InputCmdMessage) WithID

func (i *InputCmdMessage) WithID(id ClientID) ClientMessage

WithID implements ClientMessage.

type InputReadingData added in v0.0.6

type InputReadingData map[InputReadingDataKey]int

InputReadingData: properties map for InputReadingMessage.Data.

type InputReadingDataKey added in v0.0.6

type InputReadingDataKey string

InputReadingDataKey represents valid keys in InputReadingData.

const (
	InputReadingDataBattery  InputReadingDataKey = "Battery"
	InputReadingDataRSSI     InputReadingDataKey = "Rssi"
	InputReadingDataPressure InputReadingDataKey = "Pressure"
	InputReadingDataButton   InputReadingDataKey = "Button"
)

Constants for valid keys in InputReadingData.

type InputReadingMessage

type InputReadingMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ServerID `json:"Id"`
	// DeviceIndex: index used for referencing the device in device messages.
	DeviceIndex  DeviceIndex      `json:"DeviceIndex"`
	FeatureIndex int              `json:"FeatureIndex"`
	Data         InputReadingData `json:"Data"`
}

InputReadingMessage: returns from either a sensor read request or a subscribed sensor event.

func (*InputReadingMessage) LogValue

func (i *InputReadingMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*InputReadingMessage) ServerID

func (i *InputReadingMessage) ServerID() ServerID

ServerID implements ServerMessage

func (*InputReadingMessage) Type

func (i *InputReadingMessage) Type() MessageType

Type returns MessageTypeInputReading.

type InternalMessage

type InternalMessage struct{}

InternalMessage is a special type that the library uses for internal-only messages. Messages of this type were never emitted from the server.

func (InternalMessage) MarshalJSON

func (m InternalMessage) MarshalJSON() ([]byte, error)

MarshalJSON returns an error because internal messages cannot be marshaled.

func (InternalMessage) Type

func (m InternalMessage) Type() MessageType

Type returns an empty string for internal messages.

type Message

type Message interface {
	// Type returns the message type of the message.
	Type() MessageType
	// contains filtered or unexported methods
}

Message represents a single message in the buttplug.io protocol.

The following messages are defined:

type MessageType

type MessageType string

MessageType is the type string used to identify a buttplug.io message from the wire.

const (
	// MessageTypeDeviceList is the type string for a [DeviceListMessage].
	MessageTypeDeviceList MessageType = "DeviceList"
	// MessageTypeError is the type string for a [ErrorMessage].
	MessageTypeError MessageType = "Error"
	// MessageTypeInputCmd is the type string for a [InputCmdMessage].
	MessageTypeInputCmd MessageType = "InputCmd"
	// MessageTypeInputReading is the type string for a [InputReadingMessage].
	MessageTypeInputReading MessageType = "InputReading"
	// MessageTypeOK is the type string for a [OKMessage].
	MessageTypeOK MessageType = "Ok"
	// MessageTypeOutputCmd is the type string for a [OutputCmdMessage].
	MessageTypeOutputCmd MessageType = "OutputCmd"
	// MessageTypePing is the type string for a [PingMessage].
	MessageTypePing MessageType = "Ping"
	// MessageTypeRequestDeviceList is the type string for a [RequestDeviceListMessage].
	MessageTypeRequestDeviceList MessageType = "RequestDeviceList"
	// MessageTypeRequestServerInfo is the type string for a [RequestServerInfoMessage].
	MessageTypeRequestServerInfo MessageType = "RequestServerInfo"
	// MessageTypeScanningFinished is the type string for a [ScanningFinishedMessage].
	MessageTypeScanningFinished MessageType = "ScanningFinished"
	// MessageTypeServerInfo is the type string for a [ServerInfoMessage].
	MessageTypeServerInfo MessageType = "ServerInfo"
	// MessageTypeStartScanning is the type string for a [StartScanningMessage].
	MessageTypeStartScanning MessageType = "StartScanning"
	// MessageTypeStopAllDevices is the type string for a [StopAllDevicesMessage].
	MessageTypeStopAllDevices MessageType = "StopAllDevices"
	// MessageTypeStopDeviceCmd is the type string for a [StopDeviceCmdMessage].
	MessageTypeStopDeviceCmd MessageType = "StopDeviceCmd"
	// MessageTypeStopScanning is the type string for a [StopScanningMessage].
	MessageTypeStopScanning MessageType = "StopScanning"
)

All defined message types.

type OKMessage

type OKMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ClientID `json:"Id"`
}

OKMessage: signifies successful processing of the message indicated by the id.

func (*OKMessage) ClientID

func (o *OKMessage) ClientID() ClientID

ClientID implements ClientMessage

func (*OKMessage) LogValue

func (o *OKMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*OKMessage) Type

func (o *OKMessage) Type() MessageType

Type returns MessageTypeOK.

func (*OKMessage) WithID

func (o *OKMessage) WithID(id ClientID) ClientMessage

WithID implements ClientMessage.

type OutputCmd added in v0.0.6

type OutputCmd map[OutputCmdKey]OutputCmdValueType

OutputCmd: properties map for OutputCmdMessage.Command.

type OutputCmdKey added in v0.0.6

type OutputCmdKey string

OutputCmdKey represents valid keys in OutputCmd.

const (
	OutputCmdVibrate              OutputCmdKey = "Vibrate"
	OutputCmdRotate               OutputCmdKey = "Rotate"
	OutputCmdOscillate            OutputCmdKey = "Oscillate"
	OutputCmdConstrict            OutputCmdKey = "Constrict"
	OutputCmdSpray                OutputCmdKey = "Spray"
	OutputCmdPosition             OutputCmdKey = "Position"
	OutputCmdTemperature          OutputCmdKey = "Temperature"
	OutputCmdLED                  OutputCmdKey = "Led"
	OutputCmdPositionWithDuration OutputCmdKey = "PositionWithDuration"
)

Constants for valid keys in OutputCmd.

type OutputCmdMessage

type OutputCmdMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ClientID `json:"Id"`
	// DeviceIndex: index used for referencing the device in device messages.
	DeviceIndex DeviceIndex `json:"DeviceIndex"`
	// FeatureIndex: index used for referencing the device in device messages.
	FeatureIndex DeviceIndex `json:"FeatureIndex"`
	Command      OutputCmd   `json:"Command"`
}

OutputCmdMessage: sends a generic value set command to a device.

func (*OutputCmdMessage) ClientID

func (o *OutputCmdMessage) ClientID() ClientID

ClientID implements ClientMessage

func (*OutputCmdMessage) LogValue

func (o *OutputCmdMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*OutputCmdMessage) Type

func (o *OutputCmdMessage) Type() MessageType

Type returns MessageTypeOutputCmd.

func (*OutputCmdMessage) WithID

func (o *OutputCmdMessage) WithID(id ClientID) ClientMessage

WithID implements ClientMessage.

type OutputCmdPositionWithDurationValue added in v0.0.6

type OutputCmdPositionWithDurationValue struct {
	Position float64 `json:"Position"`
	Duration float64 `json:"Duration"`
}

OutputCmdPositionWithDurationValue is the value matching pattern for OutputCmdPositionWithDuration of OutputCmd.

type OutputCmdValue added in v0.0.6

type OutputCmdValue struct {
	Value float64 `json:"Value"`
}

OutputCmdValue is the value matching pattern for OutputCmdVibrate, OutputCmdRotate, OutputCmdOscillate, OutputCmdConstrict, OutputCmdSpray, OutputCmdPosition, OutputCmdTemperature and OutputCmdLED of OutputCmd.

type OutputCmdValueType added in v0.0.6

type OutputCmdValueType interface {
	// contains filtered or unexported methods
}

OutputCmdValueType is a type that represents possible values of the map OutputCmd.

The following types can be used for this interface:

type Payload

type Payload []Message

Payload is a list of messages sent from the buttplug.io websocket server. Use this type to parse each message in the payload.

func (Payload) LogValue

func (p Payload) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (Payload) MarshalJSONTo

func (p Payload) MarshalJSONTo(encoder *jsontext.Encoder) error

MarshalJSONTo writes the payload as the JSON websocket wire protocol.

func (*Payload) UnmarshalJSONFrom

func (p *Payload) UnmarshalJSONFrom(decoder *jsontext.Decoder) error

UnmarshalJSONFrom implements json.UnmarshalerFrom. It consumes one full array of messages from the given JSON decoder.

type PingMessage

type PingMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ClientID `json:"Id"`
}

PingMessage: connection keep-alive message.

func (*PingMessage) ClientID

func (p *PingMessage) ClientID() ClientID

ClientID implements ClientMessage

func (*PingMessage) LogValue

func (p *PingMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*PingMessage) Type

func (p *PingMessage) Type() MessageType

Type returns MessageTypePing.

func (*PingMessage) WithID

func (p *PingMessage) WithID(id ClientID) ClientMessage

WithID implements ClientMessage.

type RangeInclusive

type RangeInclusive [2]int

RangeInclusive: serialization of Rust's RangeInclusive Type.

type RequestDeviceListMessage

type RequestDeviceListMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ClientID `json:"Id"`
}

RequestDeviceListMessage: request for the server to send a list of devices to the client.

func (*RequestDeviceListMessage) ClientID

func (r *RequestDeviceListMessage) ClientID() ClientID

ClientID implements ClientMessage

func (*RequestDeviceListMessage) LogValue

func (r *RequestDeviceListMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*RequestDeviceListMessage) Type

Type returns MessageTypeRequestDeviceList.

func (*RequestDeviceListMessage) WithID

WithID implements ClientMessage.

type RequestServerInfoMessage

type RequestServerInfoMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ClientID `json:"Id"`
	// ClientName: name of the client software.
	ClientName string `json:"ClientName"`
	// ProtocolVersionMajor: message template version of the server software.
	ProtocolVersionMajor int `json:"ProtocolVersionMajor"`
	// ProtocolVersionMinor: message template version of the server software.
	ProtocolVersionMinor int `json:"ProtocolVersionMinor"`
}

RequestServerInfoMessage: request server version, and relay client name.

func (*RequestServerInfoMessage) ClientID

func (r *RequestServerInfoMessage) ClientID() ClientID

ClientID implements ClientMessage

func (*RequestServerInfoMessage) LogValue

func (r *RequestServerInfoMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*RequestServerInfoMessage) Type

Type returns MessageTypeRequestServerInfo.

func (*RequestServerInfoMessage) WithID

WithID implements ClientMessage.

type ScanningFinishedMessage

type ScanningFinishedMessage struct {
	// ID: used for non-direct-reply messages that can only be sent from server
	// to client, using the reserved system message Id of 0.
	ID SystemID `json:"Id"`
}

ScanningFinishedMessage: server notification to client that scanning has ended.

func (*ScanningFinishedMessage) LogValue

func (s *ScanningFinishedMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*ScanningFinishedMessage) Type

Type returns MessageTypeScanningFinished.

type ServerID

type ServerID int

ServerID: user-set id for the message. 0 denotes system message and is reserved.

type ServerInfoMessage

type ServerInfoMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ptr.Optional[ClientID] `json:"Id,omitzero"`
	// MaxPingTime: maximum time (in milliseconds) the server will wait between
	// ping messages from client before shutting down.
	MaxPingTime ptr.Optional[int] `json:"MaxPingTime,omitzero"`
	// ProtocolVersionMajor: message template version of the server software.
	ProtocolVersionMajor ptr.Optional[int] `json:"ProtocolVersionMajor,omitzero"`
	// ProtocolVersionMinor: message template version of the server software.
	ProtocolVersionMinor ptr.Optional[int] `json:"ProtocolVersionMinor,omitzero"`
	// ServerName: name of the server. Can be 0-length.
	ServerName ptr.Optional[string] `json:"ServerName,omitzero"`
}

ServerInfoMessage: server version information, with API version in Major.Minor format.

func (*ServerInfoMessage) LogValue

func (s *ServerInfoMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*ServerInfoMessage) Type

func (s *ServerInfoMessage) Type() MessageType

Type returns MessageTypeServerInfo.

type ServerMessage

type ServerMessage interface {
	Message
	// ServerID returns the ID field of the message.
	ServerID() ServerID
	// contains filtered or unexported methods
}

ServerMessage represents a message that can be sent from the server to the client. It extends Message.

The following messages are defined:

type StartScanningMessage

type StartScanningMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ClientID `json:"Id"`
}

StartScanningMessage: request for the server to start scanning for new devices.

func (*StartScanningMessage) ClientID

func (s *StartScanningMessage) ClientID() ClientID

ClientID implements ClientMessage

func (*StartScanningMessage) LogValue

func (s *StartScanningMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*StartScanningMessage) Type

Type returns MessageTypeStartScanning.

func (*StartScanningMessage) WithID

WithID implements ClientMessage.

type StopAllDevicesMessage

type StopAllDevicesMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ClientID `json:"Id"`
}

StopAllDevicesMessage: stops all actions currently being taken by all connected devices.

func (*StopAllDevicesMessage) ClientID

func (s *StopAllDevicesMessage) ClientID() ClientID

ClientID implements ClientMessage

func (*StopAllDevicesMessage) LogValue

func (s *StopAllDevicesMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*StopAllDevicesMessage) Type

Type returns MessageTypeStopAllDevices.

func (*StopAllDevicesMessage) WithID

WithID implements ClientMessage.

type StopDeviceCmdMessage

type StopDeviceCmdMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ClientID `json:"Id"`
	// DeviceIndex: index used for referencing the device in device messages.
	DeviceIndex DeviceIndex `json:"DeviceIndex"`
}

StopDeviceCmdMessage: stops the all actions currently being taken by a device.

func (*StopDeviceCmdMessage) ClientID

func (s *StopDeviceCmdMessage) ClientID() ClientID

ClientID implements ClientMessage

func (*StopDeviceCmdMessage) LogValue

func (s *StopDeviceCmdMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*StopDeviceCmdMessage) Type

Type returns MessageTypeStopDeviceCmd.

func (*StopDeviceCmdMessage) WithID

WithID implements ClientMessage.

type StopScanningMessage

type StopScanningMessage struct {
	// ID: user-set id for the message. 0 denotes system message and is
	// reserved.
	ID ClientID `json:"Id"`
}

StopScanningMessage: request for the server to stop scanning for new devices.

func (*StopScanningMessage) ClientID

func (s *StopScanningMessage) ClientID() ClientID

ClientID implements ClientMessage

func (*StopScanningMessage) LogValue

func (s *StopScanningMessage) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (*StopScanningMessage) Type

func (s *StopScanningMessage) Type() MessageType

Type returns MessageTypeStopScanning.

func (*StopScanningMessage) WithID

WithID implements ClientMessage.

type SystemID

type SystemID int

SystemID: used for non-direct-reply messages that can only be sent from server to client, using the reserved system message Id of 0.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL