mqttosc

README

mqtt-osc

This library provides a mechanism to issue Open Sound Control messages on MQTT events. Currently the flow of information is only supported from MQTT to OSC. There is also a simple command line application providing the basic relaying of messages. Using the library provides much more power of control.

Usage CLI

There is a simple command line interface for this library. You can download the binary for your platform in the Release section. Configuration is done via a YAML file. The tool provides you with a command to create a initial configuration file. Just do:

mqtt-osc config config.yaml

This will create the file config.yaml. Then open this file in your favorite text editor and tweak it for your usage.

# Hostname of the MQTT broker (aka server).
mqtt_host: 127.0.0.1
# Port of the MQTT broker (aka server).
mqtt_port: 1883
# Sets the Client-ID when connecting to the MQTT broker.
mqtt_client_id: mqtt-osc-relay
# Username for the authentication against the MQTT broker.
mqtt_user: user
# Password for the authentication against the MQTT broker.
mqtt_password: secret
# Hostname of the OSC server where the OSC command should be sent to.
osc_host: 127.0.0.1
# Port of the OSC server where the OSC command should be sent to.
osc_port: 8765
# A list of handlers. Each handler defines a MQTT topic which will be
# trigerred by. For More information see below.
handlers:
- mqtt_topic: /light/+/on
  osc_address: /light/{{ ._1 }}/turn-on
  # If true, the payload of the MQTT event will be relayed to the OSC
  # server as a string content.
  relay_payload: false

Documentation

Index

• type LogLevel
  • func (l LogLevel) String() string
• type Logger
• type MqttToOscHandler
• type Relay
  • func (r *Relay) Serve()
• type TranslateFunc

Types

type LogLevel

type LogLevel int

LogLevel describes the different levels of importance a logging message can have.

const (
	// TraceLevel represents the lowest logging level for tracing.
	TraceLevel LogLevel = iota
	// DebugLevel represents the second lowest logging level and is used for
	// debug messages.
	DebugLevel
	// InfoLevel represents logging messages a user should see during the
	// execution of the library.
	InfoLevel
	// WarnLevel represents the logging level if something noteworthy happened
	// which likely could be or lead to unintended behavior.
	WarnLevel
	// ErrorLevel represents events which seriously intercept the execution
	// of the application.
	ErrorLevel
	// PanicLevel represents events which will lead to a panicking of the
	// application.
	PanicLevel
)

func (LogLevel) String

func (l LogLevel) String() string

type Logger

type Logger func(level LogLevel, format string, args ...interface{})

Logger is the log function used in the library. It takes the message and defines the handling of this message. The message can be used as format string.

type MqttToOscHandler

type MqttToOscHandler struct {
	// Path to the MQTT topic to be listen to.
	MqttTopic string `yaml:"mqtt_topic"`
	// OscAddress points to the address the OSC command should be sent
	// on an MQTT event. Learn more about the ability to apply templates
	// in the Handler type documentation.
	OscAddress string `yaml:"osc_address"`
	// Translate is the function which can be used to alter the output
	// OSC address and payload. It gets the concrete MQTT topic which was
	// called as well as the payload (if any). It returns a map of strings
	// which will be applied to the template in the OSC address. Note that
	// no keys beginning with `_` (ex `_1`) are allowed in this map as these
	// are used to store the content of the wildcard match-groups.
	Translate *TranslateFunc `yaml:"-"`
	// RelayPayload states whether the MQTT message should be relayed to
	// the OSC recipient.
	RelayPayload bool `yaml:"relay_payload"`
	// contains filtered or unexported fields
}

MqttToOscHandler listen to one MQTT event and describes the effects it will have. This library contains some handler functions for the most common cases.

To increase the flexibility of the handlers the output OSC Address can contain template items. The Translate function can be used to define the data for this template. The matching-groups from the MQTT topic can be accessed by index using `{{ ._1 }}`. The content of the MQTT payload (also known as message) can be accessed using the `{{ .Payload }}` argument.

type Relay

type Relay struct {
	// MqttHost is the hostname of the MQTT broker.
	MqttHost string `yaml:"mqtt_host"`
	// MqttPort is the port of the MQTT broker.
	MqttPort int `yaml:"mqtt_port"`
	// MqttClientId sets the MQTT Id of this Relay.
	MqttClientId string `yaml:"mqtt_client_id"`
	// MqttUser states the user name used for the authentication
	// with the MQTT broker.
	MqttUser string `yaml:"mqtt_user"`
	// MqttUser states the password used for the authentication
	// with the MQTT broker.
	MqttPassword string `yaml:"mqtt_password"`
	// OscHost is the hostname of the OSC server.
	OscHost string `yaml:"osc_host"`
	// OscPort is the port of the OSC server.
	OscPort int `yaml:"osc_port"`
	// Handlers is the collection of handler the relay handles.
	Handlers []MqttToOscHandler `yaml:"handlers"`
	// LogFunc provides the possibility to customize the log functionality.
	// The function is called on each log. If no method is set, the debug
	// output will be outputted to standard output.
	LogFunc *Logger `yaml:"-"`
}

Relay provides the forwarding of messages from MQTT to OSC. It consist contains a slice of Handlers each describing one MQTT event to be listen to.

func (*Relay) Serve

func (r *Relay) Serve()

Serve starts the MQTT client and waits for incoming updates on the topics define by the handlers.

type TranslateFunc

type TranslateFunc func(topic string, data string) (tplData map[string]interface{}, payload string)

TranslateFunc is the function type used to alter the outgoing OSC address template data and payload.