Arduino OSC library for GrandMA3 consoles v4

An object orientated library for Arduino to control GrandMA3 consoles with OSC over Ethernet UDP/TCP. The goal of the library is to have a smart toolbox to create your own hardware which covers your needing by endless combinations of hardware elements.

Changes for v4

support for DataPools
virtual inputs for touch screens and external I/O devices
Pools and Pages classes instead of button class
minor improvements for pages and pools functions
new Parser class which support also TCP receive
simplified network configuration, you can use TCP or UDP
no more support for extern OSC buttons, this should done with console macros

Changes for v3

global / local page() numbering
command() function for sending raw commands
fetch(), value() and jitter() functions for fader handling
buttons with callback for e.g. paging

Changes for v2

TCP support
UDP parser for echo replays to get useful informations, e.g. fader value ...
independent from the CNNMAT OSC library
change of naming conventions
change license to CC BY-NC-SA 4.0

Installation

You can install directly with the library manager of the Arduino IDE. Simply search for "gma3"

Boards

You can use any Arduino compatible board which gives you the possibility of an ethernet connection. Some boards like Teensy or STM32 Nucleo-F767ZI have an Ethernet port build in, others need an external ethernet port based e.g. on WIZnet W5500 boards like USR-ES1 or Arduino EthernetShield 2. WLAN boards like ESP32 should work but are not tested and there is no guarantee for a stable connection. There are also some Arduino based SPS controllers on the market which are ideal for rough environment using 24V.

Controllino https://www.controllino.com
Industrial Shields https://www.industrialshields.com

Ethernet Usage

The in the Arduino board example used Ethernet library only supports the Wiznet 5500 chip, used on Ethernet Shield 2 or the popular USR-ES1 module which you can buy for a small pice at aliexpress.com

Following libraries must downloaded for use with Ethernet !!! Beware, the Ethernet libraries have different init procedures !!!

WIZNet w5500 boards like Ethernet Shield 2

an Arduino compatible Ethernet libraries
- Ethernet3 https://github.com/sstaub/Ethernet3
- Ethernet https://github.com/arduino-libraries/Ethernet

Teensy 4.1 with build-in Ethernet

optional for Teensy MAC address https://github.com/sstaub/TeensyID

based on FNET

https://github.com/vjmuzik/NativeEthernet
https://github.com/vjmuzik/FNET

or LWIP based

https://github.com/ssilverman/QNEthernet

STM32duino (https://github.com/stm32duino)

https://github.com/stm32duino/STM32Ethernet
https://github.com/stm32duino/LwIP

Following Nucleo boards are supported with Ethernet: F207ZG / F429ZI / F746ZG / F756ZG / F767ZI

Hardware

The library support hardware elements like encoders, faders, buttons with some helper functions. The library allows you to use hardware elements as an object and with the use of the helper functions, code becomes much easier to write and read and to understand.

Buttons You can use every momentary push button on the market, e.g. MX Keys which are also used by MA Lighting, the keys are available with different push characters and have therefore different color markers. One pin must connect to a Digital Pin Dn the other to ground. ! A 100nF capacitor is recommended between the button pins !
Faders Recommended are linear faders with 10k Ohm from Bourns or ALPS which are available in different lengths and qualities. Beware that ARM boards like STM32-Nucleo use 3.3V, classic AVR boards like Arduino UNO use 5V. The leveler must connect to the Analog Pin An. The other pins must connect to ground and 3.3V or 5V. ! A 10nF capacitor is recommended between leveler and ground !
Rotary Encoders You can use encoders from ALPS or equivalent. The middle pin of the encoders must connect to ground, the both other pins A/B must connect to Digital Pins Dn. ! Two 100nF capacitors are recommended between the button pin A/B and ground !

Additional Advices for Analog Pins

The most problems comes from bad grounding and cables that are to long, on PCB's the shielding design is very important.

Arduino UNO, MEGA with WIZnet5500 Use AREF Pin instead +5V to the top (single pin) of the fader (100%). Use GND next to AREF and connect to the center button pin (2 pins, the outer pin is normally for the leveler) of the fader (0%)
STM32-Nucleo use IOREF Pin instead +3.3V to the top (single pin) of the fader (100%). GND to the center button pin (2 pins, the outer pin is normally for the leveler) of the fader (0%).
TEENSY 3.x with WIZnet5500 +3.3V to the top (single pin) of the fader (100%) use ANALOG GND instead the normal GND to the center button pin (2 pins, the outer pin is normally for the leveler) of the fader (0%).

Development for testing using a breadboard Test configuration with Teensy41

Usage

You can find general information about OSC on http://opensoundcontrol.org/ Please refer to the GrandMA3 manual for more information about using OSC on GrandMA3.

Here an example OSC setup in the GrandMA3 software GrandMA3 OSC Setup

If you have wishes for other functions or classes enter the discussion forum. If you find bugs make an issue, nobody is perfect.

Ethernet configuration and initialization

The Ethernet functionality is now independent from the hardware port (e.g. WIFI or other Ethernet hardware than WizNet W5500) and libraries. Behind the scenes it uses the virtual Arduino UDP class.

Before using Ethernet there a some things that must be done. It can be different between the diverse libraries.

Include the necessary #defines e.g.

Arduino or Teensy 3.x with WIZnet5500

#include "Ethernet3.h"
#include "EthernetUdp3.h"

or for the original Arduino Ethernet library

#include "Ethernet.h"

STM32-Nucleo (e.g. Nucleo-F767ZI)

#include <LwIP.h>
#include <STM32Ethernet.h>
#include <EthernetUdp.h>

Teensy 4.1 with FNET network stack

#include <TeensyID.h>
#include <NativeEthernet.h>
#include <NativeEthernetUdp.h>

Teensy 4.1 with QNEthernet network stack

#include <TeensyID.h>
#include <QNEthernet.h>

You need to define IP addresses, ports and sockets

mac - You need a unique MAC address, for Teensy 3.x / 4.1 you can use the TeensyID library on this GitHub site, for STM32-Nucleo there is a build in MAC address
localIP - You need a static IP address for your Arduino in the subnet range of network system
dns - DNS address is optional necessary
gateway - A gateway range is optional necessary
subnet - A subnet range is optional necessary
localPort - This is the destination port of your Arduino
gma3IP - This is the GrandMA3 console IP address
gma3Port - This is the destination port of the GrandMA3 console

Example must done before setup()

// Network config
#define GMA3_UDP_PORT 8000 // UDP Port configured in gma3
#define GMA3_TCP_PORT 9000 // UDP Port configured in gma3

uint8_t mac[] = {0x90, 0xA2, 0xDA, 0x10, 0x14, 0x48};
IPAddress ip(10, 101, 1, 201); // IP address of the microcontroller board
IPAddress subnet(255, 255, 0, 0); // subnet range
IPAddress dns(10, 101, 1, 100); // DNS address of your device
IPAddress gateway(10, 101, 1, 100); // Gateway address of your device
uint16_t localUdpPort = GMA3_UDP_PORT;
IPAddress gma3IP(10, 101, 1, 100); // IP address of the gma3 console
uint16_t gma3UdpPort = GMA3_UDP_PORT;
uint16_t gma3TcpPort = GMA3_TCP_PORT;

You need an UDP orTCP socket, must done before setup().

EthernetUDP udp; // for UDP connection
EthernetClient tcp; // for TCP connection

In the beginning of setup() you must start network services.

Ethernet.begin(mac, ip, dns, gateway, subnet); // for Arduino ETH library
interface(udp, gma3IP, gma3UdpPort); // for UDP
// interface(tcp, TCP, gma3IP, gma3TcpPort); // for TCP

Example

A simple example for use with an Arduino UNO with EthernetShield 2

#include <Ethernet.h>
#include "gma3.h"

// I/O config
#define BTN_KEY_1 2
#define BTN_KEY_2 3
#define BTN_KEY_3 4
#define BTN_KEY_4 5
#define ENC_1_A   6
#define ENC_1_B   7
#define ENC_2_A   8
#define ENC_2_B   9
#define BTN_CMD   10
#define FADER     A0

// Network config
#define GMA3_UDP_PORT 8000 // UDP Port configured in gma3
#define GMA3_TCP_PORT 9000 // UDP Port configured in gma3

uint8_t mac[] = {0x90, 0xA2, 0xDA, 0x10, 0x14, 0x48};
IPAddress localIp(10, 101, 1, 201); // IP address of the microcontroller board
IPAddress subnet(255, 255, 0, 0); // optional subnet range
IPAddress dns(10, 101, 1, 100); // optional DNS address of your device
IPAddress gateway(10, 101, 1, 100); // optional Gateway address of your device
uint16_t localUdpPort = GMA3_UDP_PORT;
IPAddress gma3IP(10, 101, 1, 100); // IP address of the gma3 console
uint16_t gma3UdpPort = GMA3_UDP_PORT;
uint16_t gma3TcpPort = GMA3_TCP_PORT;

// EthernetUDP udp; // for UDP
EthernetClient tcp; // for TCP

// hardware definitions
Key key101(BTN_KEY_1, 101);
Fader fader201(FADER, 201);
Key key201(BTN_KEY_2, 201);
Key key301(BTN_KEY_3, 301);
ExecutorKnob enc301(ENC_1_A, ENC_1_B, 301);
Key key401(BTN_KEY_4, 401);
ExecutorKnob enc401(ENC_2_A, ENC_2_B, 301);
CmdButton macro1(BTN_CMD, "GO+ Macro 1");

void setup() {
	Serial.begin(9600);
	Ethernet.begin(mac, localIp);
	//interface(udp, gma3IP, gma3UdpPort); // for UDP
	interface(tcp, TCP, gma3IP, gma3TcpPort); // for TCP
	}

void loop() {
	key101.update();
	key201.update();
	key301.update();
	key401.update();
	fader201.update();
	enc3

Gma3

Install / Use

README