linnstrument

package module
v1.0.3 Latest Latest
Warning

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

 Go to latest Published: Jun 6, 2021 License: MIT Imports: 9 Imported by: 5

README

linnstrument

This is a library for programming the LinnStrument (https://www.rogerlinndesign.com/linnstrument).

Based on the user firmware modeof the LinnStrument (see https://github.com/rogerlinndesign/linnstrument-firmware/blob/master/user_firmware_mode.txt) this library helps to create programs with Go that get the pad presses and set the lights.

Status

Stable and usable with firmware version 2.2.1 and later.

Features

Practically all that is possible with the user firmware mode:

  • switch user firmware mode on and off
  • get pad presses
  • set colors of pads

Additionally a little gimmick:

  • show colored text on the LinnStrument

Installation

go get -d -u gilab.com/golinnstrument/linnstrument

Documentation (library)

https://pkg.go.dev/gitlab.com/golinnstrument/linnstrument

Examples

See https://gitlab.com/golinnstrument/linnstrument/-/tree/master/example.

Documentation

Overview

Package linnstrument provides a library that helps developing applications for the LinnStrument (http://www.rogerlinndesign.com).

The LinnStrument comes in two flavors, LinnStrument200 and the LinnStrument128 with 200 and 128 playable led pads. This library supports both via the Device interface.

In addition to the playable led pads, both devices have a "control column" on the left where 8 led pads are located that won't play MIDI notes, but are used by the factory firmware to allow to control its settings.

This library allows to set all available colors[1] and receive pressing and releasing events for both control pads and playable pads. Whenever the row and column of a led pad is send or returned, the column 0 denotes the control pads and the columns >= 1 the playable pads. The row however starts from top to bottom where top is 0 and bottom is 7.[3]

The LinnStrument allows to get pressing and releasing events for both control pads by switching to the "user firmware mode"[3] where most of the factory firmware functionality is off. This mode allows the developer to control the LinnStrument without interfering of the factory firmware. Only the "Global Setting" control pad keeps its behavior, allowing the user to switch between user firmware mode and factory firmware mode while pressing UPDATE OS for 0.5 sec. It is also possible to set the firmware mode by sending a MIDI message to the device. To achieve this, UserFirmwareMode can be used. The user firmware mode is set implicitely when the StartListening method is called and unset when the device is closed.

[1] See http://www.rogerlinndesign.com/ls-global-settings.html in section "Note Lights On/Off" for details about the underlying technique.

[2] This is the reverse of the underlying MIDI where the rows are counted from bottom to top, but we found it more convenient and helpful especially when using the library to trigger clips for Bitwig Studio and Reaper/Playtime.

[3] See https://github.com/rogerlinndesign/linnstrument-firmware/blob/master/user_firmware_mode.txt for details about firmware modes.

Index

Constants

This section is empty.

Variables

View Source 
var (

	// RecommendedSleepDur is the recommended time to sleep between color setting calls to the LinnStrument
	RecommendedSleepDur = time.Microsecond * 150
)

Functions

func DataDecimation 

func DataDecimation(rateMS uint8) midi.Message

the value corresponds to the number of milliseconds between data updates (minimum 12 ms in low power mode)

func Greeter 

func Greeter(d Device) error

func Marquee 

func Marquee(m Device, s string, dur time.Duration, textcolor, bgcolor Color) (err error)

Marquee displays the given string in a marquee-like manner on the device (from right to left).

func Print 

func Print(m Device, s string, textcolor, bgcolor Color) (err error)

Print prints the given string to the device. If the string is too long, anything too long is not printed

func SetRune 

func SetRune(rn rune, l string)

SetRune adds or replaces a representation of the given rune to allow "printing" of the rune on the LinnStrument. This repesentations are used by the functions Print, Greeting and Marquee to display text on the LinnStrument. The representation string must have 8 lines of same length, where each line may only contain either the '_' (underscore) or '#' (hash) character. The line length may vary from one rune representation to another. For the ASCII alphanumerical and punktuation runes there are predefined representations.

Types

type Color 

type Color uint8

Color is a possible color of a Linnstrument pad. 

const (
	ColorAsNoteLights Color = 0 // as set in Note Lights settings
	ColorRed          Color = 1
	ColorYellow       Color = 2
	ColorGreen        Color = 3
	ColorCyan         Color = 4
	ColorBlue         Color = 5
	ColorMagenta      Color = 6
	ColorOff          Color = 7
	ColorWhite        Color = 8
	ColorOrange       Color = 9
	ColorLime         Color = 10
	ColorPink         Color = 11
)

func (Color) Pad 

func (c Color) Pad(row, column uint8) ColorWriter

Pad returns a ColorWriter for the pad at position row, column

func (Color) Value 

func (c Color) Value() uint8

type ColorWriter added in v0.5.1 

type ColorWriter struct {
	Row    uint8
	Column uint8
	Color  Color // 0-11, set color constants
}

ColorWriter can be used to write the coloring to an io.Writer or to a midi.Writer

func (ColorWriter) Write added in v0.5.1 

func (p ColorWriter) Write(wr midi.Writer) error

Write writes the midi to set the color of the pad to the given midi.Writer

func (ColorWriter) WriteTo added in v0.5.1 

func (p ColorWriter) WriteTo(wr io.Writer) (int64, error)

WriteTo writes the midi bytes to set the color of the pad to the given io.Writer.

type Device 

type Device interface {

	// SetXData enables/disables sending of X-axis data for the given row
	SetXData(row uint8, enable bool) error

	// SetYData enables/disables sending of Y-axis data for the given row
	SetYData(row uint8, enable bool) error

	// SetZData enables/disables sending of Z-axis data for the given row
	SetZData(row uint8, enable bool) error

	// SetSlide enables/disables sending of slide data for the given row
	SetSlide(row uint8, enable bool) error

	// SetDataDecimation sets the data decimation
	SetDataDecimation(rateMS uint8) error

	// SetUserFirmwareMode sets the User Firmware mode (false: disable, true: enable)
	SetUserFirmwareMode(on bool) error

	// SetColor sets the pad at the given row and column to the given color.
	// Note that the first column (0) is the control pads on the left.
	// The rows are counted from top to bottom.
	SetColor(row, column uint8, color Color) error

	// SetColorAll sets all but the control pads to the given color. It has
	// reasonable sleeping time between the MIDI transmission to not
	// overload the LinnStrument.
	SetColorAll(color Color)

	// Cols returns the number of cols for the LinnStrument including
	// the control pads. Is 17 for the LinnStrument128 and 26 for the LinnStrument200.
	Cols() uint8

	// Rows returns the number of rows. Should always be 8.
	Rows() uint8

	// NumButtons returns the total number of buttons/pads, including the
	// control pads.
	NumButtons() uint8

	// String returns the name of the LinnStrument.
	String() string

	// StartListening starts the user firmware mode and listens on the pad presses of the LinnStrument
	// and calls the given function for each press and release of a pad.
	// If velocity is 0, the key was released, otherwise pressed with the given velocity.
	// Note that the rows count from top to bottom and the col starts with the control pads on the left.
	StartListening(Listener)

	// Close closes the connection of the LinnStrument and returns to the factory
	// firmware.
	Close() error
}

Device is a common interface for both the LinnStrument128 and the LinnStrument200.

func Find128 

func Find128(drv midi.Driver) (Device, error)

Find128 tries to find a LinnStrument on a MIDI port by looking for the string "LinnStrument" in the port name which would be only there, if the LinnStrument is connected via USB. The first port that is found is opened and a device is returned that would be appropriate for a LinnStrument128

func Find200 

func Find200(drv midi.Driver) (Device, error)

Find200 tries to find a LinnStrument on a MIDI port by looking for the string "LinnStrument" in the port name which would be only there, if the LinnStrument is connected via USB. The first port that is found is opened and a device is returned that would be appropriate for a LinnStrument200

func New128 

func New128(in midi.In, out midi.Out) Device

New128 returns a device that is appropriate for the LinnStrument128 an connects it via the given MIDI in and out ports.

func New200 

func New200(in midi.In, out midi.Out) Device

New200 returns a device that is appropriate for the LinnStrument200 an connects it via the given MIDI in and out ports.

type Error 

type Error struct {
	X            uint8
	Y            uint8
	WrappedError error
	Task         string
}

func (Error) Error 

func (e Error) Error() string

type Errors 

type Errors struct {
	Task   string
	Errors []error
}

func (*Errors) Add 

func (m *Errors) Add(err error)

func (*Errors) Error 

func (m *Errors) Error() string

func (*Errors) Len 

func (m *Errors) Len() int

type Listener 

type Listener interface {

	// OnTouch is called, when a pad has been touched
	OnTouch(row, col, velocity uint8)

	// OnXDataMSB is called, when the MSB part of x-axis data was received (only when X-data was enabled on the device)
	OnXDataMSB(row, col uint8, globalMSB uint8)

	// OnXDataLSB is called, when the LSB part of x-axis data was received (only when X-data was enabled on the device)
	OnXDataLSB(row, col uint8, globalLSB uint8)

	// OnYData is called, when y-axis data was received (only when y-data was enabled on the device)
	OnYData(row, col, val uint8)

	// OnZData is called, when z-axis data was received (only when z-data was enabled on the device)
	OnZData(row, col, val uint8)

	// OnSlideTransition is called, when a slide transition message was received  (only when slide mode was enabled on the device)
	OnSlideTransition(row, col uint8)

	// OnUserFirmwareMode is called, when user firmware mode was enabled/disabled on the device
	// restoreColors function can be called to set the colors according to the last state that was set via SetColor calls.
	OnUserFirmwareMode(on bool, restoreColors func())
}

Listener listens for messages received from the LinnStrument

type Row 

type Row uint8 // Row starts counting from 0 (top) to 7 (bottom)

func (Row) Slide 

func (r Row) Slide(enable bool) midi.Message

func (Row) XData 

func (r Row) XData(enable bool) midi.Message

XData returns a midi message that enableds/disables the sending of the X-axis data for the row

func (Row) YData 

func (r Row) YData(enable bool) midi.Message

YData returns a midi message that enableds/disables the sending of the X-axis data for the row

func (Row) ZData 

func (r Row) ZData(enable bool) midi.Message

ZData returns a midi message that enableds/disables the sending of the X-axis data for the row

type UserFirmwareMode 

type UserFirmwareMode bool

UserFirmwareMode allows to set (true) or unset (false) the user firmware mode.

func (UserFirmwareMode) ScanReader 

func (f UserFirmwareMode) ScanReader(rd *reader.Reader, callback func(userFirmwareState bool))

ScanReader provides a comfortable way to scan the given reader.Reader for firmware mode messages and calls the given callback, if any such message came in. If the user firmware mode is activated userFirmwareState is true, if the factory firmware mode is activated, userFirmwareState is false. Please keep in mind, that this overrides the Msg.Channel.ControlChange.NRPN.LSB handler. If you need to combine with your custom NRPN LSB handler, set it on the reader before passing the reader to this function. Then for any non firmware mode related NRPN LSB your custom handler will be called. The NRPN MSB handler however is not affected at all, since the MSB value is not significant for the firmware mode message.

func (UserFirmwareMode) Write 

func (f UserFirmwareMode) Write(wr midi.Writer) error

Write writes the MIDI messages to set (true) or unset (false) the user firmware mode to the given midi.Writer.

func (UserFirmwareMode) WriteTo 

func (f UserFirmwareMode) WriteTo(wr io.Writer) (int64, error)

Write writes the MIDI messages to set (true) or unset (false) the user firmware mode to the given io.Writer.

Source Files

View all Source files

Directories

Path Synopsis
example
linnstep Module
linnswitch Module
linnusermode Module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.