Kuandohub Manual

Home , Blink (SIP client), Jingle (protocol)

kuandoHUB Manual

Version: 0.9.19

Content 1. Introduction ...... 2 2. Colors ...... 3 3. Sounds ...... 4 4. Hotkeys ...... 5 5. Kuando TIMER ...... 6 Troubleshooting - If the Busylight is not working ...... 6 Which Busylight is connected? ...... 7 6. Outlook Options ...... 8 7. Platform Priorities ...... 9 Built-In Data Sources ...... 10 Built-In Priorities ...... 11 8. Advanced Settings ...... 12 Auto-Away feature ...... 12 Timer operation ...... 12 Troubleshooting - If the Busylight is not working ...... 12 HTTP API interface ...... 12 HTTP GET API interface ...... 13 JavaScript Sample ...... 17 HTTP POST API interface ...... 18 Powershell sample ...... 23 JavaScript sample ...... 24 Appendix A – Technical color settings ...... 25 Example: Changing “Busy” from Red to Blue ...... 25 Table of default values ...... 25 Appendix B – Group Policy settings ...... 28

1 Version 0.9.19

1. Introduction The kuandoHUB offers you a variety of functionality and value to your kuando Busylight. From here you are able to fully control and configure your Busylight to operate to best fit your way of working.

A manual operation lets you change the Busylight’s light color and sound. Hotkeys provide a fast way to change your Busylight status. Outlook integration allows you to be notified for incoming emails and calendar events. Platform Priorities allow you to prioritize your different UC platforms so the Busylight signals you according to the way you want it to work. E.g. Skype for Business Call alerts get prioritized over other platform statuses, or perhaps Call events in RingCentral are more important. You decide – customize it to work for you! Kuando TIMER helps you to structure your time so you’re more productive but builds in the necessary breaks to keep us in balance. Additional Advanced Settings provide enhanced features.

If you need support for kuandoHUB, please contact [email protected].

For more information or tools to help with the implementation go to https://www.plenom.com.

2 Version 0.9.19

2. Colors Under the menu item Colors you can manually set the color of Busylight. Click on a tile and the Busylight switches to the color shown.

Note – If you have a sound selected it will not be affected and remains unchanged.

3 Version 0.9.19

3. Sounds Clicking a tile starts the selected sound.

Note – If you have a color selected it will not be affected and remains unchanged.

The volume can be configured using the slide bar. The Ringtone duration can be adjusted using the drop down.

4 Version 0.9.19

4. Hotkeys On this page you can define your own global hotkeys. Please note: The keys defined here will work in all other apps as well. If the ‘hotkey’ field remains red when you save a selection, it means the selected global hotkey could not be registered because it was previously registered by another application. Simply chose a different hotkey combination. It will show Green when registered.

You can change the hotkey color using the edit button to the right of the color selection. You will see this dialog box open and allow you to configure the desired color:

5 Version 0.9.19

5. Kuando TIMER

The kuando TIMER supports your personal time management. The underlying idea is for better efficiency by having the tasks and breaks organized in a scheduled work/break structure. The default values are commonly used to ensure a good balance.

Using the defaults you will work for 30 minutes followed by a 5 minute break in 3 sets. After set 4 you will have a longer 15 minute break.

set 1 set 2 set 3 set 4 30min 5 min 30min 5 min 30min 5 min 30min 15 min Figure 1 Example of kuandoTImer setup

Troubleshooting - If the Busylight is not working Please make sure you have enabled the appropriate Platform Priority entries (see chapter 7) to allow the Manual Changer, Outlook, HTTP, kuando TIMER and/or UC Platform access the Busylight device.

The Platform entries needs to be present and enabled in your Platform Priorities.

6 Version 0.9.19

The marked checkboxes should be active to ensure manual modes working. Which Busylight is connected?

To find out which Busylight model is connected, open the About Page. There you will find a list of all the Busylights that are connected:

7 Version 0.9.19

6. Outlook Options If Microsoft Outlook is installed, then this menu option will become available. There are three options to configure:

Calendar reminder: The Busylight will give you a reminder for an upcoming appointment. It requires that the appointment was marked for a reminder in Outlook and will follow the same logic as in Outlook.

In a Meeting state: The Busylight will show if you are in a Meeting which was scheduled in Outlook. Require that Platform Priorities are configured accordingly (see chapter 7).

NewMail Notification: The Busylight will provide a notification when a new mail arrives. You can configure color and jingle here.

8 Version 0.9.19

7. Platform Priorities

Platform Priorities is a powerful feature of kuandoHUB. This allows you to determine how the Busylight will respond when operating with multiple UC Platforms and/or other setting options as the kuandoTimer and Manual Color and Sound features.

You will not only need to select which Platform is most important, but also which components of the Event Type are most important. For example, Skype for Business – Alerts. There are options allowing you to choose between ‚All‘ – ‚Call Alert‘ and or ‚IM Alert‘. (See the second screenshot below) There are similar choices for the other options that you can explore. These entries are then positioned from top to bottom to control how the Busylight will react based upon the event.

Click the Edit button to configure.

9 Version 0.9.19

Let’s go through an example of the setup below. In this configuration, the grey bars are showing that the kuandoHUB is currently receiving information from MS Teams and Manual Changer. As MS Team has a higher priority on the list, MS Teams is currently controlling the general presence status.

However, you’ll notice that we have priorities above the Teams entry. What this means is that if we get a ‘Notification’ from Outlook; or an ‘Alert’ from Skype for Business; or if Skype for Business Presence changes to ‘On the Phone’ or ‘Do Not Disturb’, then these will override the Teams Presence setting and the Busylight will respond accordingly.

Built-In Data Sources These Data Sources are native built-in with kuandoHUB:

• HTTP • Manual Changer • Outlook • Kuando TIMER

Note: If you have installed the latest release of our Busylight software, e.g. Busylight for Skype for Business, Busylight for Cisco Jabber or similar then they will automatically add the appropriate Entry into kuandoHUB Platform Priorities.

10 Version 0.9.19

Built-In Priorities The table below shows how the priorities are configured the first time the program starts or when a reset is done to factory defaults.

Data Source Event Type Event Names Outlook Notification New Mail + Calendar Reminder Outlook Presence In a Meeting Kuando TIMER Presence (all) Manual Changer (all) (all)

11 Version 0.9.19

8. Advanced Settings

Auto-Away feature The Auto-Away feature will set your Busylight device to „Away“ (yellow), if you lock your PC (or if it locks itself). The locked state will override all other Busylight settings.

Timer operation The Timer has ability to change the color of the Busylight after a specified amount of time. For example; It can be used if you want to be in Do Not Disturb mode for 1 hour while you complete a project. You can then select what the Busylight will do after the timer expires - switch off or to change to a different color. When the timer is enabled, the remaining time will be shown on this page. Troubleshooting - If the Busylight is not working The timer is controlled under Manuel Changer in the Platform Priorities (see Chapter 7). Please make sure to enable and configure accordingly.

HTTP API interface KuandoHUB has an integrated HTTP interface to control the Busylight from your own software.

To use the HTTP interface, it needs to be enabled. You can find the control switch to enable the HTTP interface in the Advanced Settings tab.

12 Version 0.9.19

A second option is to set the registry values. See Appendix B for details.

The HTTP Server access token is only required for remote access from other devices.

The HTTP server URL can only be set from the Registry. If the value cannot be processed, the http server will be disabled.

For details about the HTTP server URL, see here: https://docs.microsoft.com/en- us/dotnet/api/system.net.httplistener

The http server access token is only used if a request is coming from a remote server.

HTTP GET API interface The HTTP GET interface is a very simple interface to control the Busylight. A http get command can be sent from an internet browser or a webhook as an example.

The HTTP GET interface is dedicated to the HTTP data source to be used in the Platform priorities page.

The HTTP get priority needs to be enabled in order to control the Busylight.

13 Version 0.9.19

Below are the GET Requests that can be made: The examples show local requests which do not need a security token.

If a security token is needed, it is added as an additional parameter (http_token=tokendata)

If you want to use the default value, then you do not need to provide a parameter.

Light command: http://localhost:8989?action=light&red=100&green=100&blue=100

Parameters:

Parameter Name Values Red 0..100 (Default 0) Green 0..100 (Default 0) Blue 0..100 (Default 0)

Alert Command: http://localhost:8989?action=alert&red=100&sound=5&volume=25

Parameters:

Parameter Name Values Red 0..100 (Default 0) Green 0..100 (Default 0) Blue 0..100 (Default 0) Sound 0..8 (See list)

14 Version 0.9.19

Volume 0..100 (See list)

Sound list:

Sound Sound number (No Sound) 0 Fairy Tale 1 Funky 2 Kuando Train 3 (Default) Open Office 4 Quiet 5 Telephone Nordic 6 Telephone original 7 Telephone Pick Me Up 8

Volume can be set to these values:

Volume Volume value 100% 100 75% 75 (Default) 50% 50 25% 25 Mute 0

Blink command http://localhost:8989?action=blink&blue=100

Parameters:

Parameter Name Values Red 0..100 (Default 0) Green 0..100 (Default 0) Blue 0..100 (Default 0) Ontime (0.1 seconds steps light on) Default: 5 (0.5 Seconds) Offtime (0.1 seconds steps light off) Default: 5 (0.5 Seconds)

Jingle command http://localhost:8989?action=jingle&red=100&sound=3&volume=100

Parameters:

Parameter Name Values Red 0..100 (Default 0) Green 0..100 (Default 0)

15 Version 0.9.19

Blue 0..100 (Default 0) Sound 0..8 (See list) Volume 0..100 (See list)

For Sound and Volume values, see the Alert command.

Pulse command http://localhost:8989?action=pulse&blue=100&red=100

Parameters:

Parameter Name Values Red 0..100 (Default 0) Green 0..100 (Default 0) Blue 0..100 (Default 0)

ColorWithFlash command http://localhost:8989?action=colorwithflash&green=100&red=100&flashblue=100

Parameters:

Parameter Name Values Red 0..100 (Default 0) Green 0..100 (Default 0) Blue 0..100 (Default 0) flashred 0..100 (Default 0) flashgreen 0..100 (Default 0) flashblue 0..100 (Default 0)

Off command http://localhost:8989?action=off

The Off-Command has no parameters associated with it. kuandoTimer command http://localhost:8989?action=kuandoTimer&command=start

Parameters:

Parameter Name Values command start,stop,pause,mcontinue,reset

16 Version 0.9.19

PowerShell Sample

Invoke-WebRequest -URI "http://localhost:8989?action=light&red=100&green=100&blue=100"

JavaScript Sample const Http = new XMLHttpRequest(); const url='http://localhost:8989?action=light&red=0&green=100&blue=0'; Http.open("GET", url); Http.send();

Http.onreadystatechange = (e) => { console.log(Http.responseText) }

17 Version 0.9.19

HTTP POST API interface The HTTP POST interface can be used by any software which is able to do a HTTP POST request, e.g. PowerShell, JavaScript inside a Browser or a desktop app.

The HTTP POST interface enables all SDK functionalities including registering Priority configuration and Data Sources.

The HTTP POST interface accepts json data.

Common Parameters The json structure has four common parameters, which control the kuandoHUB operation.

Parameter Name Values action Command for kuandoHUB sender Datasource for kuandoHUB priority operation eventtype Event Type for kuandoHUB priority operation eventname The name of the specific event for kuandoHUB priority operatrion parameter This property contains an embedded json structure with the parameters for the specific action. The structure is different and specific for each action. (See examples below.)

Light command: { "action":"Light", "sender":"SDK", "eventtype":"Light", "eventname":"Color", "parameter":"{ \"RedRgbValue\":0, \"GreenRgbValue\":100, \"BlueRgbValue\":0 }" }

Parameters:

Parameter Name Values RedRgbValue 0..100 (Default 0) GreenRgbValue 0..100 (Default 0) BlueRgbValue 0..100 (Default 0)

18 Version 0.9.19

Alert Command: { "action":"Alert", "sender":"SDK", "eventtype":"Alert", "eventname":"Alert", "parameter":"{ \"color\":{ \"RedRgbValue\":255, \"GreenRgbValue\":0, \"BlueRgbValue\":0 }, \"clip\":5, \"volume\":50 }" }

Parameters:

Parameter Name Values RedRgbValue 0..100 (Default 0) GreenRgbValue 0..100 (Default 0) BlueRgbValue 0..100 (Default 0) Clip 0..8 (See list) Volume 0..100 (See list)

Sound list:

Clip Sound number (No Sound) 0 Fairy Tale 1 Funky 2 Kuando Train 3 (Default) Open Office 4 Quiet 5 Telephone Nordic 6 Telephone original 7 Telephone Pick Me Up 8

Volume can be set to these values:

Volume Volume value 100% 100 75% 75 (Default) 50% 50 25% 25 Mute 0

Blink command {

19 Version 0.9.19

"action":"Blink", "sender":"SDK", "eventtype":"Blink", "eventname":"Blink", "parameter":"{ \"color\":{ \"RedRgbValue\":255, \"GreenRgbValue\":0, \"BlueRgbValue\":0 }, \"ontime\":5, \"offtime\":5 }" }

Parameters:

Parameter Name Values RedRgbValue 0..100 (Default 0) GreenRgbValue 0..100 (Default 0) BlueRgbValue 0..100 (Default 0) Ontime (0.1 seconds steps light on) Default: 5 (0.5 Seconds) Offtime (0.1 seconds steps light off) Default: 5 (0.5 Seconds)

Jingle command { "action":"Jingle", "sender":"SDK", "eventtype":"Jingle", "eventname":"Jingle", "parameter":"{ \"color\":{ \"RedRgbValue\":255, \"GreenRgbValue\":255, \"BlueRgbValue\":0 }, \"clip\":9, \"volume\":50 }" }

Parameters:

Parameter Name Values RedRgbValue 0..100 (Default 0) GreenRgbValue 0..100 (Default 0) BlueRgbValue 0..100 (Default 0) Clip 0..8 (See list) Volume 0..100 (See list)

For Sound and Volume values, see Alert command.

Pulse command { "action":"Pulse", "sender":"SDK",

20 Version 0.9.19

"eventtype":"Pulse", "eventname":"Pulse", "parameter":"{ \"color\":{ \"RedRgbValue\":255, \"GreenRgbValue\":255, \"BlueRgbValue\":0 }, \"pulsesequence\":{ \"Color\":{ \"RedRgbValue\":255, \"GreenRgbValue\":255, \"BlueRgbValue\":0 }, \"Step1\":3, \"Step2\":21, \"Step3\":36, \"Step4\":50, \"Step5\":36, \"Step6\":21, \"Step7\":10 } }" }

Parameters:

Parameter Name Values RedRgbValue 0..100 (Default 0) GreenRgbValue 0..100 (Default 0) BlueRgbValue 0..100 (Default 0) Step1 .. Step7 Intensity of the step (0..100)

ColorWithFlash command { "action":"ColorWithFlash", "sender":"SDK", "eventtype":"Light", "eventname":"ColorWithFlash", "parameter":"{ \"color\":{ \"RedRgbValue\":0, \"GreenRgbValue\":255, \"BlueRgbValue\":0 }, \"flash\":{ \"RedRgbValue\":0, \"GreenRgbValue\":0, \"BlueRgbValue\":255 } }" }

Parameters:

The color parameter determines the solid color, the color of the short flashes. Both colors are defined as designated in the parameter table:

Parameter Name Values RedRgbValue 0..100 (Default 0)

21 Version 0.9.19

GreenRgbValue 0..100 (Default 0) BlueRgbValue 0..100 (Default 0)

Off command { "action":"Off", "sender":"SDK", "eventtype":"Light", "eventname":"Off", "parameter":"" }

The Off-Command has no specific parameters.

RegisterDataSource command This command allows you to register a custom data source in kuandoHUB for priority operation. It is recommended to send this command on every connect to kuandoHUB to make sure that the data source exists and has the most recent version. See kuandoHUB operation chapter for details.

{ "action":"RegisterDataSource", "sender":null, "eventtype":null, "eventname":null, "parameter":"{ \"DataSourceName\":\"SDK\", \"eventnames\":{ \"Light\":{ \"EventNames\":[ \"Light\", \"Green\", \"Red\", \"Yellow\", \"Off\"], \"IsAlertPriority\":false }, \"Alert\":{ \"EventNames\":[ \"Alert\", \"Other Notification\"], \"IsAlertPriority\":true } } }" }

CreateInitialPriority command The CreateInitialPriority command allows to create Priority entries in the kuandoHUB priority operation.

{ "action":"CreateInitialPriority", "sender":null, "eventtype":null, "eventname":null, "parameter":"{ \"enabled\":true, \"sender\":\"SDK\", \"eventtype\":null, \"eventnames\":[],

22 Version 0.9.19

\"IsAlertPriority\":false }" }

This command creates a line in kuandoHUB priorities with the data Source name “SDK” containing all eventtypes and event names.

The command will have no effect if a line containing the data source name is already in the kuandoHUB priorities list.

Powershell sample This command switches the Busylight to green light. Please make sure you have registered the SDK DataSource and have an enabled priority line entry in kuandoHUB.

$lightcmd = '{"action":"Light","sender":"SDK","eventtype":"Light","eventname":"Color","parameter":"{ \"RedRgbValue\":0,\"GreenRgbValue\":100,\"BlueRgbValue\":0}"}'

Invoke-WebRequest -Body $lightcmd -Method 'POST' -Uri 'http://localhost:8989'

Example of configuration in kuandoHUB:

23 Version 0.9.19

JavaScript sample This commands switches the Busylight to green light. Please make sure you have registered the SDK DataSource and have an enabled priority line entry in kuandoHUB.

const Http = new XMLHttpRequest(); const url='http://localhost:8989'; Http.open("POST", url);

Http.send('{"action":"Light","sender":"SDK","eventtype":"Light","eventname":"Color","par ameter":"{\\"RedRgbValue\\":0,\\"GreenRgbValue\\":100,\\"BlueRgbValue\\":0}"}'); Http.onreadystatechange = (e) => { console.log(Http.responseText) }

Please note the double-escaped quotes in the parameter section.

24 Version 0.9.19

Appendix A – Technical color settings kuandoHUB has predefined color settings for presence states with the colors Red, Green, Purple (do not disturb), blue (ringing) and yellow. The predefined color values and their dynamic behavior can be changed via registry keys. These keys are stored in the path HKCU\Software\Busylight and can be changed or added via registry key or centrally via group policies. Changes may be also applied after installation of the Busylight software. Example: Changing “Busy” from Red to Blue The registry keys allows you to control the values of the Red/Green/Blue (RGB) colors in the Busylight LED light (0-100 per cent). To open Registry Editor, run regedit in Windows. To change the color for Busy (see screenshot below): 1. Insert two new DWORD values 2. Set Red to 0 (to cancel default value) 3. Set Blue to e.g. 50 (per cent)

You can also mix the basic colors to create new ones, e.g. Purple is a mix of Blue (value: 60), Green (value: 40) and Red (value: 1). To have a unified color scheme within an organization, it is recommended that you distribute the changed configuration via group policies.

Table of default values The following table contains all registry keys, which are used by Busylight, along with the default values if the key does not exist:

25 Version 0.9.19

Registry Key Data Description Default New type Value Default Busylight Busylight Alpha Omega Away Blue DWORD Blue value for „Away“, 0 0 Green DWORD Green value for „Away“ 18 100 Red DWORD Red value for „Away“ 16 89 Busy Blue DWORD Blue value for „Busy“ 0 0 Green DWORD Green value for „Busy“ 0 0 Red DWORD Red value for „Busy“ 50 100 BusyInACallColor STRING „Pulse“ or „Red“ „Pulse“ „Pulse“ BusyInCallSequence Step1 DWORD Color intensity for „on the 7 14 phone“, Step 1 Step2 DWORD Color intensity for „on the 21 42 phone“, Step 2 Step3 DWORD Color intensity for „on the 36 72 phone“, Step 3 Step4 DWORD Color intensity for „on the 50 100 phone“, Step 4 Step5 DWORD Color intensity for „on the 36 72 phone“, Step 5 Step6 DWORD Color intensity for „on the 21 42 phone“, Step 6 Step7 DWORD Color intensity for „on the 10 20 phone“, Step 7 BusyInCallSequence Red DWORD Red value for „on the phone“ 50 100 Green DWORD Green value for „on the 0 0 phone“ Blue DWORD Blue value for „on the 0 0 phone“ Free Blue DWORD Blue value for „Available“ 0 0 Green DWORD Green value for „Available“ 50 100 Red DWORD Red value for „Available“ 0 0 DoNotDisturb Blue DWORD Blue value for „Do not 60 100 disturb“ Green DWORD Green value for „Do not 1 2 disturb“ Red DWORD Red value for „Do not 40 67 disturb“ Ringing Blue DWORD Blue value for „Ringing“ 100 100 Green DWORD Green value for „Ringing“ 0 0 Red DWORD Red value for „Ringing“ 0 0 Off Blue DWORD Blue value for „Offline“ 0 0 Green DWORD Green value for „Offline“ 0 0 Red DWORD Red value for „Offline“ 0 0

26 Version 0.9.19

Registry Key Data Description Default Value type (Decimal) ActualBusylightVolume DWORD The volume of the Busylight 3 Sounds Auto_Away DWORD Auto-Away feature on 0 (1)/off (0) http_enabled DWORD Enables (1)/Disables (0) the 0 http interface http_uri SZ Listening URL http://localhost:8989/ Outlook_enabled DWORD Enables (1) / Disables (0) 1 Outlook integration. Does not have effect if Outlook is not installed. automation_enabled DWORD Enables (1) / Disables (0) 0 COM automation interface. For future use. ringtonelength DWORD 5 ColorsPageEnabled DWORD 1 SoundsPageEnabled DWORD 1 HotkeysPageEnabled DWORD 1 PrioritesPageEnabled DWORD 1 PomodoroPageEnabled DWORD 1 AdvancedOptionsPageEnabled DWORD 1

The following table contains special registry keys:

Registry Key Data type Description Default Value (Decimal)

SDKLogLevel DWORD Log level for USB communication 0 0: no messages 1: verbose logging

27 Version 0.9.19

Appendix B – Group Policy settings

It is possible to predefine Corporate standards on any setting via group policy. The kuandoHUB app checks the Software\Policies\Busylight sections for existence of any of the registry keys listed in the previous chapter.

If a setting is found in the Policies sections, it will override any user setting and disable the corresponding user menu items. Users can still see the predefined settings, but not change them.

Upon application start, the registry sections will be checked in this order: 1. HKEY_LOCAL_MACHINE\Software\Policies\Busylight 2. HKEY_CURRENT_USER\Software\Policies\Busylight 3. HKEY_CURRENT_USER\Software\Busylight 4. HKEY_LOCAL_MACHINE\Software\Busylight

The first value found in this order will be applied. If nothing is found in the registry, kuandoHUB applies the intrinsic default values defined in the previous chapter.

Changes of group policy values will be applied on the fly without needing to restart the software.

This software package contains registry files as samples for the convenience of the system administrators.

To apply a policy to users it can be published using this powershell command from the server: Invoke-GPUpdate –Computer -Force -RandomDelayInMinutes 0

Or, from the client PC: GPUpdate /force

28 Version 0.9.19