Arduino GetInTouch Library

Program Your Own Gadgets

Tutorial - How to use the Arduino GetInTouch Library

Introduction

GetInTouch is a Twitch Extension which provides an easy interface to connect an arduino to the stream. To give you the opportunity to create your own cool (and unique) gadget for the GetInTouch Extension, we provide an Arduino library. This allows you to program your own gadgets.The viewers can then control your arduino over the extension.
To use the Arduino as a GetInTouch gadget you'll need:

  • A Twitch account as a streamer
  • GetInTouch extension on your Twitch dashboard
  • GetInTouch application and
  • An Arduino board connected to your PC (via USB)
Further information on how to setup GetInTouch can be found in our Getting Started section.

Supported Arduino boards

The following Arduino boards are supported:

  • Arduino MEGA ADK
  • Arduino MEGA 2560
  • Arduino NANO
  • Arduino UNO
Leonardo boards are not supported.

Install Library

To install the GetInTouch Arduino library open Arduino and go to the Library Manager (Sketch → Include Library → Manage Libraries...).

Search for "GetInTouch" and click the Install Button.
This will install the library and some code examples.

Getting Started

You can implement up to 10 actions in your Arduino code. Each action is identified by its name. So, you have to pay attention and make sure each action has a unique name.
First you have to include the library and create an instance of our GetInTouch class and an instance for each action you want to create. This has to be placed at the beginning of your code. Here is an example to create an action:

#include <GetInTouch.h>

GetInTouch git;
GITAction ledBlinkAction("LED blink");

In your setup function you have to initialize the git object and add your actions to it:

void setup() {
 git.init();
 git.addAction(&ledBlinkAction);
}

You can add up to 10 actions. If you add more, the new ones will be ignored, and the function will return with false. The name of an action has some restrictions:

  • Minimum 5 signs long
  • Maximum 40 signs long
  • Recommended characters are a-z A-Z 0-9 ,.!? ( ) Space
  • Forbidden characters are | ; % ~
  • Unique (each name can only be used once)

If your action name doesn't fulfill these requirements, it will be ignored by the library or you will get some errors in your Extension.

The library works only when you call the run() method in your main loop:

void loop() {
 git.run();
}

Now your actions are displayed in your Twitch Extension with their given names.

Please keep in mind that you have to activate them on the GetInTouch config page to make them available to your viewers.

Additionally, you will get an Arduino Monitor in the right-click menu of the GetInTouch-Icon in your task menu. With this entry you can open the Arduino Monitor. If you want to know more about this helpful tool, take a look at the Arduino Monitor chapter.

To react on an action triggered by the viewer, each action object provides an isTriggered() method. You have to poll this method regularly. If this method returns true, the action was triggered.

IMPORTANT: When your action is finished, you have to call the ended() method! Until you call this method your action will be unavailable in the Extension for the next viewer who wants to trigger it.

This is how a simple action-is-triggered-cycle may look like:

void loop() {
 git.run();

 if(ledBlinkAction.isTriggered()) {
     //... do some stuff
     ledBlinkAction.ended();
 }
}
The isTriggered() method will return true until you have called the ended() method.

That's all for the basic stuff.
You can also find this basic example in your Arduino IDE in the menu
File → Examples → GetInTouch → simpleAction

User Inputs

The GetInTouch library supports input fields, which gives you the ability to get user inputs from your viewers to your Arduino. Our GetInTouch library currently supports four types of viewer inputs:

Combobox
Combobox

The viewer can choose between some predefined values

Textbox
Textbox

Textbox where the viewer can type in individual text.

The Slider
Slider

Slider where the viewer can adjust a value.

Pixel Matrix
Pixel Matrix

Pixel Matrix where the viewer can set a color of each pixel.


To use such inputs, you have to call the appropriate add functions in the setup:

void setup() {
 ledBlinkAction.addCombobox("select color", "red|green|blue");
 displayAction.addTextbox("enter your message", 5, 40);
 displayAction.addSlider("count", 3, 10, 5);
 ledMatrix.addPixelMatrix("draw your image", 8, 8);
 
 git.init();
 git.addAction(&ledBlinkAction);
 git.addAction(&displayAction);
 git.addAction(&ledMatrix);
}
It is important to add the input fields to the action before you add the action to your git object.
You can combine multiple input fields. You can add up to three input fields to an action.

Combobox Input

To use a combobox follow the example above for the "ledBlink" action. The declaration of the method is:
bool addCombobox(String label, String values);

  • label will be displayed together with the combobox
  • values are the items separated by the "|" character

Returns false when the parameters are wrong or invalid, otherwise it returns true.

Textbox Input

To make a textbox input field take a look at the "displayAction" action above. The declaration of the method is:
bool addTextbox(String label, uint8_t min, uint8_t max);

  • label will be displayed together with the textbox
  • min amount of minimum characters which the user has to enter. (0 - 255 allowed)
  • max amount of characters which the user can enter maximum. (1 - 255 allowed)

Returns false when the parameters are wrong or invalid, otherwise it returns true.

Slider Input

A slider input is useful when numbers are needed from viewers, take a look at the "displayAction" action example above.
bool addSlider(String label, int min, int max, int start);

  • label will be displayed together with the slider value
  • minimum (min) value of the slider (can also be negative)
  • maximum (max) value of the slider (has to be greater than the min value)
  • start sets default value of the slider

Returns false when the parameters are wrong or invalid, otherwise it returns true.

Pixel Matrix Input

Shows a pixel Matrix to the viewers. They can set a color of each individual LED in the Matrix.
bool addPixelMatrix(String label, uint8_t cols, uint8_t rows);

  • label will be displayed together with the slider value
  • cols number of columns of your matrix (2 - 32 allowed)
  • rows number of rows of your matrix (2 - 32 allowed)

Returns false when the parameters are wrong or invalid, otherwise it returns true.

Get Viewer's Input

To receive input from users, you can read the parameter of the according action:

 if(ledBlink.isTriggered()) {
   String color;
   color = ledBlink.getParameter(0);
   color = ledBlink.getParameter("select color");
   ledBlink.ended();
 }
You have two options to get the parameter:
  • You can get it by index. The input field you added first will be available under index 0, the second under index 1 and so on.
  • You can also get the parameter by its label string.


Pixel Matrix Value

If you use a pixel matrix input, the string which will be returned from the getParameter function contains a representative number for each color due to this list:

  • 0: black (off)
  • 1: red
  • 2: green
  • 3: blue
  • 4: white
  • 5: yellow
  • 6: orange

The order begins on the top left corner and goes through each row from left to right, top to bottom.

So the following drawn matrix will result in the following string:

"2220133516650444"

Integer Values

Sometimes viewer input consists of numbers (for example the slider or maybe a combobox selection of numbers). In this case you can also directly get the integer value of the parameter by calling getIntParameter(...) with the same schema:

int value;
value = displayAction.getIntParameter(1);
value = displayAction.getIntParameter("count");

Get Username

Additionally, the name of the user who triggered the action is part of the GITAction object. For example, you can show this username on a display:

lcd.print("user: " + ledBlink.getUsername());

You can also find this example in your Arduino IDE in the menu
File → Examples → GetInTouch → UserInputs

Handle Multiple Actions Parallel

If your code for the action contains long delays, the git.run() method will not be called for longer time. In this case new actions will not be handled, and your viewers will get an error. To run long time actions, you can do something like this:

void loop() {
 delay(10);
 git.run();

 if(ledBlink.isTriggered()) {
     doLedBlink();
 }
 if(displayAction.isTriggered()) {
     doDisplayAction();
 }
}

void doLedBlink()
{
 static int cnt = 0;
 if(!(cnt % 20)) {
   digitalWrite(13, !digitalRead(13));
 }
 cnt++;
 if(cnt >= 600) {
   cnt = 0;
   digitalWrite(13, LOW);
   ledBlink.ended();
 }
}

void doDisplayAction()
{
 static int cnt = 0;
 if(cnt == 0) {
   digitalWrite(10, HIGH);
 }
 cnt++;
 if(cnt >= 600) {
   cnt = 0;
   digitalWrite(10, LOW);
   displayAction.ended();
 }
}

Keep in mind, that the ended() function moved into the subroutines because this function has to be called if the action is really finished.

You can also find this example in your Arduino IDE in the menu
File → Examples → GetInTouch → parallelActions

Arduino Monitor

You can open the Arduino Monitor by right-clicking the GetInTouch icon in the task menu.

NOTE: This menu entry will be available only if you have connected an Arduino board which creates a COM-Port.
GetInTouch Arduino Monitor

This monitor is a very helpful tool to work with Arduino within the GetInTouch application. It has the following features:

  1. This selection box shows all serial ports found as a GetInTouch device (Arduino board with a program using our GetInTouch library).
    If you work with multiple boards you can select the board which you want to monitor in this box.
  2. The GetInTouch application will keep the COM port open as long as it runs. If you want to upload new code to your Arduino, you have to close the COM Port here manually. After uploading your code, open the port here and all your new programmed actions will be available in your Twitch Extension.
  3. In this combobox you find all actions you added to your code. If you select one and click the "trigger" button, this action triggers. This gives you the possibility to test your action directly without opening the Twitch website.
    If your action has some parameters (see chapter User inputs), you can enter the parameter in the textbox and this will be sent to your Arduino.
    If your action has more than one parameter, you can separate them with a "|" character.
  4. This button opens the log file with more detailed log information. This shows you all low-level port communication, including COM-ports which are not detected as a GetInTouch Arduino Gadget.
    If your board won't appear in the combobox (1) you may find out what's wrong in this logfile.
  5. In the list you will see all communication commands sent and received on selected (1) board.

If you like to get in touch with us join our Discord Channel, post your creation or ask questions.

Function Description

GITAction::GITAction(String name)
Description
  • constructor for an action.
Parameter
  • name of the action

bool GITAction::addTextbox(String label, uint8_t min, uint8_t max)
Description
  • will add a textbox to your action.
    This function should be called in your setup.
Parameter
  • label will be displayed together with the textbox
  • min amount of minimum characters which the user has to enter. (0 - 255 allowed)
  • max amount of characters which the user can enter maximum. (1 - 255 allowed)
Return
  • returns false when the parameters are wrong or invalid, otherwise it returns true.

bool GITAction::addCombobox(String label, String values)
Description
  • will add a combobox selection to your action. This combobox will be presented to the viewer after he has triggered this action.
    This function should be called in your setup.
Parameter
  • label will be displayed together with the combobox
  • values all options separated with a "|" character
Return
  • will return false when the parameters are wrong or invalid, otherwise it will return true.

bool GITAction::addSlider(String label, int min, int max, int start)
Description
  • will add a slider to your action. This slider will be presented to the viewer after he has triggered this action.
    This function should be called in your setup.
Parameter
  • label will be displayed together with the slider value
  • min minimum value of the slider
  • max maximum value of the slider
  • start sets default value of the slider
Return
  • will return false when the parameters are wrong or invalid, otherwise it will return true.

bool GITAction::addPixelMatrix(String label, int cols, int rows)
Description
  • will add a pixel matrix to your action. This matrix will be presented to the viewer after he has triggered this action.
    This function should be called in your setup.
Parameter
  • label to identify the action in the getParameter function
  • cols number of columns of your matrix (2 - 32 allowed)
  • rows number of rows of your matrix (2 - 32 allowed)
Return
  • will return false when the parameters are wrong or invalid, otherwise it will return true.

void GITAction::ended()
Description
  • When your action is finished you have to call this method to release it in your Extension.
    As long as you don't call this function, your action will be disabled for the viewers in the Extension.

bool GITAction::isTriggered()
Description
  • If a viewer has triggered this action, this function will return true.
    You should call this function periodically.
Return
  • true if the action was triggered (will stay true until ended() method is called).

String GITAction::getParameter(uint8_t index)
Description
  • If you have added input fields to your action,
    you can get the appropriate parameter which the viewer has selected or inserted.
Parameter
  • index : The index of the parameter (order as you have added the fields, beginning with 0).
Return
  • parameter value as String.

String GITAction::getParameter(String name)
Description
  • If you have added input fields to your action, you can get the appropriate parameter which the viewer has selected or inserted.
Parameter
  • name : The label after which you named the parameter in the add method.
Return
  • parameter value as String.

int GITAction::getParameter(uint8_t index)
Description
  • If you have added input fields to your action, you can get the appropriate parameter which the viewer has selected or inserted.
    This method is particular for the case when you expect an integer value. It tries to convert the user input into int.
    If this is not possible, it returns 0.
Parameter
  • index : The index of the parameter (order as you have added the fields, beginning with 0).
Return
  • value of userinput as integer

int GITAction::getIntParameter(String name)
Description
  • If you have added input fields to your action, you can get the appropriate parameter which the viewer has selected or inserted.
    This method is particular for the case when you expect an integer value. It tries to convert the userinput into int.
    If this is not possible, it returns 0.
Parameter
  • name the label you have given the parameter in the add method.
Return
  • value of userinput as integer.

String GITAction::getUsername()
Description
  • Returns the username of the viewer who triggered the action.
Return
  • username.

GetInTouch::GetInTouch()
Description
  • constructor

void GetInTouch::init()
Description
  • Initializes the Serial port and internal members.

bool GetInTouch::addAction(GITAction* action)
Description
  • Will add an action to your Extension.
    This function should be called in your setup().
Parameter
  • action : A reference to your (completely initialized) GITAction.
Return
  • Will return false when the parameters are wrong or invalid, otherwise it will return true.

void GetInTouch::run()
Description
  • Will handle the Serial inputs and communication to your GetInTouch application
    This function must be called periodically.

If you have problems...

I cannot upload new programs to my Arduino
Open the Arduino Monitor (right click on the GetInTouch Icon in your task bar) and press the "close now" button.

I can't select/find my Arduino board in Arduino Monitor
  • Click refresh button in Arduino Monitor.
  • Check if the COM port is not used by any other program (e.g. Serial Monitor in Arduino IDE)
  • If you know the port number of your board, look in the low level log file (4) to see what went wrong on this port.
  • Check if the board you use is compatible with our library (see chapter Supported Arduino boards).
My action will not appear on Twitch Extension
Make sure you have completed the following important steps:
  • Call the git.init();
  • Add some actions with git.addAction(&action); and
  • Call the git.run() in your loop periodically.
Keep in mind that the Twitch Extension configuration panel will only get refreshed if you are not in the editing mode.
In case of doubt: press F5 to reload the page.
My action didn't start after I triggered it
  • Make sure that you call the git.run() method periodically.
  • Make sure that you check action.isTriggered() method periodically.
The action.isTriggered() method always returns true
  • Have you forgot to call the action.ended() method?
    The isTriggered() method will return true as long as an action is running. Call the action.ended() method to end the action. Thereafter isTriggered() method will return false.