buttplug

README

go-buttplug

import "libdb.so/go-buttplug"

A Go library for the Intiface Websocket API, including Intiface Central and Intiface Engine, which wraps the buttplug.io protocol.

Example

See cmd/vibrate-em-all for a simple example program that vibrates all connected devices.

Documentation

Overview

Package buttplug provides Go wrappers around the Intiface API, which is a wrapper around the buttplug.io specifications.

Most people should use package intiface instead. This package only supplies the messages and the Websocket implementation, but intiface allows those to automatically interact with the Intiface server.

Index

• Constants
• Variables
• type Websocket
  • func NewWebsocket(wsAddr string, opts *WebsocketOpts) *Websocket
  • func (w *Websocket) MessageChannel(ctx context.Context) (<-chan buttplugschema.Message, context.CancelFunc)
  • func (w *Websocket) Send(ctx context.Context, msg buttplugschema.ClientMessage) (buttplugschema.ClientID, error)
  • func (w *Websocket) SendCommand(ctx context.Context, cmd buttplugschema.ClientMessage) (buttplugschema.Message, error)
  • func (w *Websocket) Start(ctx context.Context) error
• type WebsocketOpts
• type WebsocketResetMessage

Constants

const (
	ActuatorUnknown   = "Unknown"
	ActuatorVibrate   = "Vibrate"
	ActuatorRotate    = "Rotate"
	ActuatorOscillate = "Oscillate"
	ActuatorConstrict = "Constrict"
	ActuatorInflate   = "Inflate"
	ActuatorPosition  = "Position"
)

Actuator type constants.

const (
	SensorUnknown  = "Unknown"
	SensorBattery  = "Battery"
	SensorRSSI     = "RSSI"
	SensorButton   = "Button"
	SensorPressure = "Pressure"
)

Sensor type constants.

const DefaultDialTimeout = 10 * time.Second

DefaultDialTimeout is the maximum duration each dial.

const DefaultServerName = "go-buttplug"

DefaultServerName is the default client name sent to the Buttplug server during handshake.

const MessageVersion = 3

MessageVersion is the current Buttplug message version this library implements. See https://docs.buttplug.io/docs/spec/changelog.

Variables

var DefaultDialBackoff backoff.BackOff = &backoff.ExponentialBackOff{
	InitialInterval:     200 * time.Millisecond,
	RandomizationFactor: 0.5,
	Multiplier:          1.5,
	MaxInterval:         2 * time.Second,
}

DefaultDialBackoff is the default backoff policy for reconnecting to a Buttplug server over websocket.

Types

type Websocket

type Websocket struct {
	// contains filtered or unexported fields
}

Websocket describes a websocket connection to the Buttplug server.

func NewWebsocket

func NewWebsocket(wsAddr string, opts *WebsocketOpts) *Websocket

NewWebsocket creates a new Buttplug Websocket client instance with optionally a WebsocketOpts to configure it.

func (*Websocket) MessageChannel

func (w *Websocket) MessageChannel(ctx context.Context) (<-chan buttplugschema.Message, context.CancelFunc)

MessageChannel returns a new channel that will receive all incoming messages coming from the Buttplug server. For convenience, this channel is closed when Websocket.Start exits or when the given context is cancelled, and no messages will be sent to the channel after that.

It is safe to call this method concurrently.

Note that if this method is called after Websocket.Start, messages may be missed. Therefore, this method should only be called before starting the websocket.

func (*Websocket) Send

func (w *Websocket) Send(ctx context.Context, msg buttplugschema.ClientMessage) (buttplugschema.ClientID, error)

Send queues the given messages to be sent in the main Websocket.Start loop. An error is only returned if context is cancelled.

It is safe to call this method concurrently.

func (*Websocket) SendCommand

func (w *Websocket) SendCommand(ctx context.Context, cmd buttplugschema.ClientMessage) (buttplugschema.Message, error)

SendCommand sends a single Buttplug command and waits for the response. This is a convenience method around Websocket.Send and listening to the message channels.

func (*Websocket) Start

func (w *Websocket) Start(ctx context.Context) error

Start starts the websocket connection persistently and blocks until the given context is cancelled. It transparently reconnects on connection or loop failure with a backoff defined by DefaultDialBackoff.

type WebsocketOpts

type WebsocketOpts struct {
	// ServerName is the client name sent to the Buttplug server during
	// handshake. It is recommended that you change this to the actual name of
	// the application using the library. If empty, [DefaultServerName] is used.
	ServerName string
	// Logger is an optional logger for internal logging.
	// If empty, [slog.Default] is used.
	Logger *slog.Logger
	// DialTimeout is the maximum duration for each dial attempt.
	// If zero, [WebsocketDialTimeout] is used.
	DialTimeout time.Duration
	// DialBackoff is the backoff policy for reconnecting to the Buttplug
	// server over websocket. If nil, [DefaultDialBackoff] is used.
	DialBackoff backoff.BackOff
}

WebsocketOpts contains options for creating a new Buttplug Websocket instance.

type WebsocketResetMessage

type WebsocketResetMessage struct {
	buttplugschema.InternalMessage
}

WebsocketResetMessage is an empty message that is sent from the websocket loop to indicate that the connection has been reset and that internal state should be cleared.