avcontrol

README

av-control-api

A RESTful API for controlling audiovisual devices

Documentation

Overview

Package avcontrol contains the structs and interfaces that are used by the rest of the packages within the av-control-api.

Index

• func CtxRequestID(ctx context.Context) string
• func WithRequestID(ctx context.Context, id string) context.Context
• type DataService
• type Device
• type DeviceConfig
• type DeviceHealth
• type DeviceID
  • func (id DeviceID) Room() string
• type DeviceInfo
• type DeviceState
• type DeviceStateError
• type DeviceWithAudioInput
• type DeviceWithAudioVideoInput
• type DeviceWithBlank
• type DeviceWithHealth
• type DeviceWithInfo
• type DeviceWithMute
• type DeviceWithPower
• type DeviceWithVideoInput
• type DeviceWithVolume
• type Driver
• type DriverRegistry
• type Input
• type PortConfig
• type PortConfigs
  • func (p PortConfigs) Names() []string
  • func (p PortConfigs) OfType(typ string) PortConfigs
• type RoomConfig
• type RoomHealth
• type RoomInfo
• type StateGetSetter
• type StateRequest
• type StateResponse

Functions

func CtxRequestID

func CtxRequestID(ctx context.Context) string

CtxRequestID pulls a request ID from a context.Context.

func WithRequestID

func WithRequestID(ctx context.Context, id string) context.Context

WithRequestID returns a new context.Context, based on ctx, with the request id set.

Types

type DataService

type DataService interface {
	RoomConfig(ctx context.Context, id string) (RoomConfig, error)
}

DataService is used by to get information about rooms.

type Device

type Device interface{}

Device is the base device interface

type DeviceConfig

type DeviceConfig struct {
	// Address is the Hostname or IP address of the device
	Address string `json:"address"`

	// Driver should match with a driver that has been registered with the API. The matching driver will be used to
	// communicate with this device. If no drivers with this name have been registered, requests will fail.
	Driver string `json:"driver"`

	// Ports are logical ports that the API must know about to be able to control. For a DSP,
	// these are control block names.
	Ports PortConfigs `json:"ports,omitempty"`
}

DeviceConfig contains information about a given device.

type DeviceHealth

type DeviceHealth struct {
	Healthy *bool   `json:"healthy,omitempty"`
	Error   *string `json:"error,omitempty"`
}

DeviceHealth contains information about the device's health status

type DeviceID

type DeviceID string

DeviceID is a string in the format of Building-Room-DeviceName

func (DeviceID) Room

func (id DeviceID) Room() string

Room returns the Building-Room portion of a DeviceID

type DeviceInfo

type DeviceInfo struct {
	Info  interface{} `json:"info,omitempty"`
	Error *string     `json:"error,omitempty"`
}

type DeviceState

type DeviceState struct {
	PoweredOn *bool `json:"poweredOn,omitempty"`
	Blanked   *bool `json:"blanked,omitempty"`

	Inputs  map[string]Input `json:"inputs,omitempty"`
	Volumes map[string]int   `json:"volumes,omitempty"`
	Mutes   map[string]bool  `json:"mutes,omitempty"`
}

DeviceState represents all of the possible fields that can can be set for a device.

type DeviceStateError

type DeviceStateError struct {
	// ID is the device that this error is associated with.
	ID DeviceID `json:"id"`

	// Field is the field (on DeviceState) that caused an error while the API was trying to get or set it.
	Field string `json:"field,omitempty"`

	// Value is the value the API was trying to set this field to when the error occurred.
	Value interface{} `json:"value,omitempty"`

	// Error is the error that happened.
	Error string `json:"error"`
}

DeviceStateError is included in StateResponse whenever there is an error getting or setting a specific DeviceState field.

type DeviceWithAudioInput

type DeviceWithAudioInput interface {
	AudioInputs(ctx context.Context) (map[string]string, error)
	SetAudioInput(ctx context.Context, output, input string) error
}

type DeviceWithAudioVideoInput

type DeviceWithAudioVideoInput interface {
	AudioVideoInputs(ctx context.Context) (map[string]string, error)
	SetAudioVideoInput(ctx context.Context, output, input string) error
}

type DeviceWithBlank

type DeviceWithBlank interface {
	Blank(context.Context) (bool, error)
	SetBlank(context.Context, bool) error
}

type DeviceWithHealth

type DeviceWithHealth interface {
	// Healthy returns a nil error if the device is healthy.
	Healthy(context.Context) error
}

type DeviceWithInfo

type DeviceWithInfo interface {
	// Info returns a struct of info about the device.
	Info(context.Context) (interface{}, error)
}

type DeviceWithMute

type DeviceWithMute interface {
	Mutes(ctx context.Context, blocks []string) (map[string]bool, error)
	SetMute(context.Context, string, bool) error
}

type DeviceWithPower

type DeviceWithPower interface {
	Power(context.Context) (bool, error)
	SetPower(context.Context, bool) error
}

type DeviceWithVideoInput

type DeviceWithVideoInput interface {
	VideoInputs(ctx context.Context) (map[string]string, error)
	SetVideoInput(ctx context.Context, output, input string) error
}

type DeviceWithVolume

type DeviceWithVolume interface {
	Volumes(ctx context.Context, blocks []string) (map[string]int, error)
	SetVolume(context.Context, string, int) error
}

type Driver

type Driver interface {
	// CreateDevice is called whenever the API needs to get or set state on
	// a device. Addr is the address (IP or hostname) of the device.
	// See Device for interfaces the returned struct should implement.
	CreateDevice(ctx context.Context, addr string) (Device, error)

	// ParseConfig is called by the DriverRegistry when a driver is registered.
	ParseConfig(map[string]interface{}) error
}

type DriverRegistry

type DriverRegistry interface {
	// Register registers a driver with the given name.
	Register(string, Driver) error

	// MustRegister is like Register but panics if there is an error registering the driver.
	MustRegister(string, Driver)

	// Get returns the driver that was registered with name.
	Get(string) Driver

	// List returns the list of names that have been registered.
	List() []string
}

DriverRegistry is the interface used to register drivers with the api

type Input

type Input struct {
	AudioVideo *string `json:"audioVideo,omitempty"`
	Audio      *string `json:"audio,omitempty"`
	Video      *string `json:"video,omitempty"`
}

Input represents the current input state for a specific output on a device. Logically, Audio/Video will not be set if AudioVideo is set.

type PortConfig

type PortConfig struct {
	// Name is the name of the port that a driver will understand and use. For example,
	// in a QSC DSP, this is the NamedControl
	Name string `json:"name"`

	// Type is the type of port this port is. There are two used types right now:
	//  - volume
	//  - mute
	// Each port is used when getting or setting that field on a device.
	Type string `json:"type"`
}

PortConfig is the configuration for a specific port

type PortConfigs

type PortConfigs []PortConfig

PortConfigs is a slice of PortConfigs

func (PortConfigs) Names

func (p PortConfigs) Names() []string

Names returns the list of names of these ports.

func (PortConfigs) OfType

func (p PortConfigs) OfType(typ string) PortConfigs

OfType returns the Ports of a specific type.

type RoomConfig

type RoomConfig struct {
	// ID is the ID of this room, in the format of Building-Room
	ID string `json:"id"`

	// Proxy is used to decide if this instance of the API should handle this request,
	// or if it should proxy the request to another instance of the API. See (handlers.Handlers{}).Proxy()
	// for more details.
	Proxy *url.URL `json:"-"`

	// Devices is map of devices that exist in this room.
	Devices map[DeviceID]DeviceConfig `json:"devices"`
}

RoomConfig is the configuration a room as perceived by the av-control-api.

type RoomHealth

type RoomHealth struct {
	Devices map[DeviceID]DeviceHealth `json:"devices,omitempty"`
}

RoomHealth maps device id to device health status for each device in the room.

type RoomInfo

type RoomInfo struct {
	Devices map[DeviceID]DeviceInfo `json:"devices,omitempty"`
}

RoomInfo maps device id to device info for each device in the room.

type StateGetSetter

type StateGetSetter interface {
	// Get gets the state for the given Room.
	// TODO change to `RoomState`, idk
	Get(context.Context, RoomConfig) (StateResponse, error)

	// Set sets the state for the given Room, based on the data in the StateRequest.
	// TODO change to `SetRoomState`
	Set(context.Context, RoomConfig, StateRequest) (StateResponse, error)

	// GetHealth returns the health status of the room
	// TODO change to `RoomHealth`
	GetHealth(context.Context, RoomConfig) (RoomHealth, error)

	// GetInfo returns the info about each device in the room
	// TODO change to `RoomInfo`
	GetInfo(context.Context, RoomConfig) (RoomInfo, error)
}

StateGetSetter represents something that can get and set device state.

type StateRequest

type StateRequest struct {
	Devices map[DeviceID]DeviceState `json:"devices,omitempty"`
}

StateRequest is the JSON object that a consumer of the av-control-api sends in a PUT request to set state

type StateResponse

type StateResponse struct {
	Devices map[DeviceID]DeviceState `json:"devices,omitempty"`
	Errors  []DeviceStateError       `json:"errors,omitempty"`
}

StateResponse is the JSON object that the API responds with when getting or setting state