KUMA Dashboard — User Guide

A touch-first control and status screen for live events. It runs next to KUMA on a wide bar display, on the second screen of a dual-screen laptop, or in any browser on a tablet or phone. No experience with this kind of software needed: this guide starts from zero.

What KUMA Dashboard is

Think of Dashboard as a programmable control panel made of tiles. Each tile (we call it a box) can show a live value, change colour when something happens, and press a button when you tap it. You decide what the boxes show and where they sit, and you save the result as your own screen layout.

Dashboard gets its information from Bitfocus Companion. Companion is the free program that connects to all kinds of show equipment (video switchers, media servers, lighting desks, audio mixers …) and, with the KUMA Timer module, to KUMA. Companion knows hundreds of live values called variables (for example the timer, the name of the running cue, which camera is on air). Dashboard reads those variables and draws them the way you want.

When you tap a box, Dashboard can press a button in Companion, which can then do anything Companion can do: start the timer, cut to a camera, fire a lighting cue. Companion does the work; Dashboard is the face.

What it is good for

Where to run it

Dashboard is designed for screens where you can touch things, but a mouse works the same way. Four common set-ups:

1. Beside KUMA on a wide bar screen

Wide bar displays (for example the 2560×720 Corsair Xeneon Edge) are made for this. KUMA runs as a slim full-height strip on one side, and Dashboard fills the rest of the screen, so the timer and your controls sit together on one display. Dashboard's wide-screen mode lines the two up for you, and it can even follow KUMA automatically (Beside KUMA).

2. On the second (touch) screen of a laptop

Dual-screen laptops such as the ASUS Zenbook Duo have a second, touch-sensitive screen below the main one. Put KUMA or your show software on the top screen and Dashboard on the bottom one: instant touch buttons for START, PAUSE, presets and cues, with the timer always in view. Any laptop with an extra touch monitor (a portable USB-C touch display works well) does the same job.

3. On a tablet or phone, in the browser

Dashboard has a built-in web server. Turn it on and the same screen opens in any browser on your network: an iPad on the production desk, a phone in the wings, a TV in the green room. Without a password the browser is view-only; with a password you can sign in and edit or press buttons from the tablet. See Web server.

4. On any computer with a mouse

Mac or Windows, in a normal window, or in full screen. Nothing needs to be installed on the show computer itself: Dashboard can run on a different computer, even on a different network from KUMA, as long as it can reach Companion.

Quick start (10 minutes)

1. Install Dashboard (macOS or Windows) and start it. Details.
2. Activate it with the same licence code you use for KUMA.
3. Connect to Companion: menu → LINK. If Companion runs on the same computer the default (127.0.0.1:8000) is already right. Details.
4. Add the KUMA boxes: menu → BOX → Presets… and press Add next to Timer with progress bar, then Status and cue and TCR. Drag them where you want them. Details.
5. Add a button: New box, type START in the value, then ACTION → Press a Companion button and enter the page / row / column of the Companion button. Details.
6. Lock the layout with the padlock at the bottom of the menu. Boxes now react to taps. Details.

That is a working control panel. The rest of this guide explains each part and then shows how to make it look the way you want.

Installing and activating

Dashboard is a normal desktop application for macOS (Apple silicon) and Windows (10 / 11). Download the installer from the Dashboard section of the download page, install it like any other program and start it.

Activating

The first screen asks for your licence code. Enter the same 16-character code you use for KUMA Timer (for example AAAA-BBBB-CCCC-DDDD) and press Activate. The computer takes one Dashboard seat on your licence, and Dashboard opens. There is no separate trial: Dashboard needs a paid KUMA licence code (the free Lite version has no code).

• One seat per computer. A single licence has one Dashboard seat; a 20-seat site licence has 20. They are counted separately from your KUMA seats, so Dashboard never uses up a KUMA seat.
• Offline is fine. Dashboard checks the licence in the background and keeps working without internet for at least two weeks, so a venue with no connection is not a problem.
• Moving to another computer. Open menu → SYS → Licence → Give this seat back, then activate on the other computer. You can also release a seat in the licence portal under KUMA Dashboard seats. If every seat is in use, Dashboard tells you which computers hold them.

A first look

After activation you see a black canvas: this is your dashboard. Everything you build lives on it. All the settings are in one menu that slides in from the left.

• The round + button at the bottom right opens the menu (or press and hold on any box or empty space for about half a second).
• A small green dot at the top right shows that Companion is reachable (red when it is not).
• The menu has a slim rail of six sections on its left edge, then the settings for the selected section.

At the top of the menu panel are Undo and Redo. Almost every change can be undone, so you can experiment freely.

Connecting to Companion

Open LINK. A new Dashboard already has one connection called Companion at 127.0.0.1:8000, which is right when Companion runs on the same computer. If Companion is on another computer, type its IP address and port instead (for example 192.168.1.60:8000). The address is shown at the top of Companion's own window.

• Status dot: green when Companion answers, red when it does not.
• Name: a short alias you can use in variables from several computers (see below).
• Star: the default connection. Boxes use it unless you say otherwise.
• Add connection for a second Companion (a second room, a second computer).
• Refresh rate in milliseconds: how often Dashboard asks for new values (300–500 ms feels live; the minimum is 100).
• Show connection status on screen: the little dots at the top right of the dashboard. Switch them off on a finished show screen if you prefer a clean look.

Your first box

Everything on a dashboard is a box. Let us build the most useful one: a live timer.

1. Open BOX and press New box. A box appears and is selected (a gold frame with handles). The settings for that box open below.

   

2. In Content → Value press + Insert variable…. The variable picker opens: on the left every module Companion knows (grouped by connection), on the right its variables with a plain description. Pick KUMA_Timer, type timer in the search box and tap timer.

   

3. The box now shows the live time. What you inserted is written in the Text (template) field as $(KUMA_Timer:timer). That is all a variable is: a name in $( ) that Dashboard replaces with the current value, several times a second.

   

4. Drag the box where you want it, drag a handle to resize it, and turn on Auto-fit text to the box so the number grows with the box.

You can mix text and variables in one box, for example Cue: $(KUMA_Timer:cue_name). If a value is missing Dashboard shows …; if Companion cannot be reached it shows ⚠.

Working on the canvas

Keyboard shortcuts

Shortcuts work while the layout is unlocked and you are not typing in a text field.

Hide is handy for boxes you only need sometimes: a hidden box is greyed out while you edit and completely invisible once the layout is locked.

Box settings: Content

With a box selected the BOX section shows tools for the selection on top and four tabs below. Content is about what the box says.

Labels

A label is a small caption on one edge of the box, such as STATE above a status or PROGRAM on a camera tile. A box can have several labels. For each label you choose:

• the text (variables work here too, for example $(KUMA_Timer:cue_name)),
• its position: top, left, centre, right or bottom, and where it sits along that edge,
• Bar on or off: a bar draws the caption as a filled strip flush with the box edge (see the blue NOW strip in the screenshots), with its own colour (colour or variable) and thickness,
• rotation for vertical text, italic, UPPERCASE, size, letter spacing and text colour (Auto uses the box's own colour, dimmed).

Value

• Text (template): what the box shows. Type text and insert variables with + Insert variable….
• Edit text on the box lets you type directly on the canvas.
• Text colour and Size, or Auto-fit text to the box, which resizes the text to fill the box (recommended for timers).
• Alignment left / centre / right and top / middle / bottom.

Formatted text

Switch the text mode from plain to formatted to use a little mark-up: **bold**, *italic*, ~~strikethrough~~, colour with {#ff0000|red}, size with {150%|bigger}, and - item at the start of a line for a bullet list. Formatting also works on text that arrives from a variable. The Formatting cheat sheet in the menu always shows the rules.

Box settings: Style

Style is about how the box looks. It is divided into folding groups so the panel stays short.

Background

A colour (pick it, type a hex code such as #1f2937, or use a variable that holds a colour) and an optional two-colour gradient with an angle. Rules can override the background (see Rules).

Image and video

Put a picture or a looping video behind the text: pick a file from your computer (it is copied into Dashboard, so it keeps working even if you move the original), give a web address, or use a variable that holds an address. Choose cover (fill and crop), contain (show all) or stretch, and set the opacity. The video sits below the image. Images can be switched by rules (for example a different icon when something is on); videos cannot.

Border and shadow

Border width and colour, corner radius, shadow (none / soft / strong) and the opacity of the whole box. The opacity can also come from a variable between 0 and 100, for example to fade a box out as something finishes.

Progress bar

Turn a box into a bar that fills as a number changes: a countdown that empties, a media clip that plays, a fader level. Set the value (a number or a variable), what value means empty and what means full, the direction the bar grows, and its colour and opacity.

For a KUMA timer press KUMA timer: use KUMA's progress (%). It uses KUMA's own progress value (0–100) which is exact for any timer length and stays right even if Dashboard is started in the middle of a countdown. A line under the settings always shows what the bar is reading right now, so you can see at once if a variable or unit is wrong.

Text style

Bold, italic, a text effect (none / shadow / outline) for readability on pictures, letter spacing, and the font for this box (the default is the global font from VIEW).

Value animation

How a changing value appears: nothing, fade, slide or flip. Default follows the global setting in VIEW. Animations are skipped automatically if the computer asks for reduced motion.

Box settings: Rules (make boxes react)

Rules are what make a dashboard come alive. A rule says: when this variable matches, change how the box looks. The first rule that matches wins, so put the most important one on top.

Example from the finished dashboard: the STATE box is grey by default, green while KUMA_Timer:status is RUNNING, orange for PAUSED and red for OVERTIME.

Each rule has:

• a variable (type it or tap … to pick it),
• a comparison: equals (=), not equal, greater / smaller (numeric), is empty, is not empty, contains, does not contain,
• a value to compare with,
• what to change when it matches: background colour, text colour, border colour, box opacity, the text itself (for example show no clip playing when nothing plays) and the image. Anything left empty (∅) stays as the box normally is.

Shortcuts for many rules

• Indicator from flag… builds an ON / OFF light in one step: pick a variable that is true or false and the box turns grey OFF and green ON.
• Add many rules copies the last rule and counts its variable up (source_1, source_2, source_3 …). Perfect for a box that must change for each of ten inputs.
• Find & replace in all rules changes a word everywhere, for example after you duplicated a box for another screen.

Rules for the whole screen

The page background can have rules as well (VIEW → Background). In the example the whole screen turns dark red while the timer is in overtime, which is hard to miss across a control room.

Box settings: Action (make boxes do something)

The Action tab says what a box does when you tap it while the layout is locked (see Locking).

Press a Companion button

Tell Dashboard which Companion button to press: the page, row and column of the button, exactly as you see them in Companion's Buttons view. If you have several Companion computers, choose which one (the default connection is used otherwise).

Go to a page

Switch the dashboard to the next, previous or first page, or to a particular page. Use it for a navigation strip.

Show on all pages

Tick Show on all pages for boxes that belong to the whole dashboard, such as a page-switch bar, a clock or a title strip. Otherwise a box lives only on the page where you created it.

Arranging many boxes

Select more than one box (drag a rectangle, or use Multi-select) and BOX shows alignment tools:

• Align left, horizontal centre, right, top, vertical middle, bottom.
• Distribute evenly horizontally or vertically (three or more boxes).
• Order: bring to front, forward, backward, send to back, for boxes that overlap.
• Duplicate and Delete. Delete all empties the page after a second confirmation press (“Sure?”).

Repeat as series

Need ten identical tiles for ten inputs? Build one, select it and press Repeat as series…. Dashboard makes numbered copies and counts the number in each variable up for you (preset_1_label, preset_2_label, …) and lays them out as a row, a column or a grid with the gap you choose. A preview shows the first and last variable before you press Create.

Save a selection as your own preset

Got a combination you will use again (a timer block, a camera tile)? Select its boxes and press Save selection as preset…. It is stored under My presets (next chapter) and can be added to any dashboard. The connection used becomes a placeholder, so the preset works with any connection of the same module.

Presets: ready-made boxes

You do not have to build everything from scratch. BOX → Presets… reads which modules your Companion has and offers matching boxes built from the variables your system really has: the number of sources, cards or screens is not typed in by you.

• Any module: a green OK / red PROBLEM tile that follows Companion's own connection status.
• KUMA Timer: Timer with progress bar, Status and cue, TCR (time left of the playing video).
• Video switchers and other modules: for example program and preview per mix effect and aux outputs for ATEM, power supplies and cards for Barco E2 / EventMaster.

Press Add to place a preset (it lands below what you already have, selected, ready to drag), or Add all for… for a whole module. Reload from Companion reads Companion again after you add a module. Under My presets are the ones you saved yourself.

One box, many sources: what is on PGM and PVW of a screen

A very common question in a production: what is on the LED wall right now, and what is waiting in preview? The answer is not one variable. A video processor such as a Barco E2 or EventMaster tells you, for every input, on which screens it is currently in program or preview. With 20 inputs that is 20 variables, and any one of them can be the answer. Dashboard solves this with one box that has one rule per input, and it has a shortcut so you do not enter the 20 rules one by one.

The idea

The E2 module in Companion gives every input two variables that list the screens it is on, for example eventmaster:source_4_pgm_destinations holds Screen LED while input 4 is in program on that screen (and is empty otherwise), plus its name eventmaster:source_4_name. (eventmaster is the connection name; yours may differ, pick the variables with … as usual.) The box looks at all inputs in turn. The first input whose list contains the screen name wins, and the box shows that input's name:

• variable source_N_pgm_destinations contains Screen LED,
• then show the text $(eventmaster:source_N_name) and colour the box red.

When nothing matches, the box keeps its normal look (grey, with a dash). If two inputs are on the same screen at once (a key over a background), the rule that is higher in the list wins, because the first matching rule wins.

Build it

1. Make the box with New box. Give it a value of — (shown when nothing matches), a big font and a bar label such as LED · PGM ("Content" tab).
2. Add the first rule (RULES → + Rule): variable eventmaster:source_1_pgm_destinations, comparison contains, value Screen LED (type the screen name exactly as the module reports it), background red, and as the rule's text $(eventmaster:source_1_name).

   

3. Add the other 19 at once. Scroll down to Add many rules, type 19 in More rules and look at the preview: it shows the last rule and the range that will be created (source_2_pgm_destinations … source_20_pgm_destinations). Press Add 19 rules.

   

   The copies keep the comparison, value and colour, and the number in the rule's text counts up together with the variable, so rule 7 reads source_7_pgm_destinations and shows $(eventmaster:source_7_name). Count by is the step, useful when inputs are numbered 1, 3, 5.

   

4. Look at the result. With input 4 in program on the LED wall the box shows its name:

   

Make the PVW box, and the same for a second screen

You do not repeat any of this. Duplicate the box (the duplicate icon in the BOX tab, or Ctrl/Cmd+D) and use Find & replace in all rules at the bottom of the Rules tab on the copy:

Finally change the bar label of the copy (Content tab) to LED · PVW. Four boxes, two screens, program and preview, and every one of them follows all 20 inputs:

Other uses of the same trick

• Router or matrix: one box per destination, one rule per source (destination_N_source, text is the source name).
• Several things in one box: end the rule list with a rule on a different variable (a warning, a fault flag). Put it at the top so it wins over everything else.
• Several sources at the same time: if one box must show two inputs (for example a key and a background), make two boxes, or use Repeat as series to lay out one box per input.
• Share the panel: SYS → Configuration → Save writes the whole dashboard into one file. Load it on another computer to get the same panel, then only change the connection in LINK.

Pages

One screen is rarely enough, so a dashboard can have several pages, like tabs. Open PAGE to add (+), rename, reorder (◀ ▶) and delete pages. Deleting a page deletes its boxes, after a confirmation press. Switch pages by tapping the page in this list, or with a box whose action is Go to a page.

Look of the whole screen (VIEW)

The VIEW section affects the entire dashboard.

Font

Choose the default font or import your own (ttf, otf, woff, woff2), for example your event's brand font. Imported fonts also appear in every box's own font list.

Scaling and design width

Dashboard draws your boxes on a canvas that is scaled to the width of the window, so a layout looks the same on a small laptop and on a large display. The design width (default 1280) is the width of that canvas in pixels. The height follows the shape of the window:

So: draw each page for the screen it will be shown on (a page for the bar, a page for the tablet). Use Use current canvas width to match the design width to the window you are working in.

Background

The colour of the page (or a variable that holds a colour), colour rules (change the whole screen when something happens, such as red in overtime), and an optional background image or video.

Animations

The default animation for changing values (none, fade, slide, flip), smooth colour changes, smooth image changes and the duration. A single box can override the value animation.

Locking: from editor to control panel

While unlocked, tapping a box selects it. While locked, tapping a box does its action (presses the Companion button or switches the page), the menu is gone and nothing can be moved by accident. Lock the layout before the show.

• Lock: press the padlock at the bottom of the menu rail.
• Unlock: press and hold the padlock button at the bottom right for one second. A ring fills up and the padlock pops open. The hold is deliberate: nobody unlocks it by an accidental tap in the dark.

Make a screen that always looks right

• Keep the big read-outs (timer, status) big and the touch buttons at least about 80 pixels on the canvas.
• Use colour with rules rather than text alone, so state is visible from across the room.
• Switch off Show connection status on screen only when you trust the link. The dots are a free early warning.

Web server: tablets, phones and TVs

Open WEB (desktop app) and switch on Enable web server. Dashboard now serves your screen to every browser on the same network. The addresses to open are listed right there, for example http://dashboard.local:8099 or the computer's IP address. Type one into the browser of an iPad, a phone or a smart TV.

• Port (default 8080) and Name (the .local name, default dashboard).
• Edit password: without one, every browser is view-only (it can look at the dashboard but not change it or press buttons). Set a password and browsers can sign in with the small key button to edit and press.
• The password is stored only as a salted hash; failed sign-ins are slowed down automatically.
• The server listens on your local network only while it is enabled.

Changes made on one device show up on the others a moment later, so you can edit on the laptop and watch the tablet update. A browser works like the app, with two differences: the WEB section and the window options (wide-screen, auto-fit) exist only in the desktop app.

Wide-screen mode: Dashboard beside KUMA

On a screen that is much wider than it is tall (2.3 : 1 or wider, such as a 2560×720 bar display) Dashboard shows a wide-screen button at the bottom of the menu rail. Tap it (or press Ctrl/Cmd + Shift + D anywhere) to turn the mode on: the window loses its title bar, takes the full usable height of the screen and snaps to a slot, so it can stand next to KUMA's own wide-screen strip.

Right-click the button, or press and hold it, to choose the options:

Beside KUMA needs KUMA on the same computer and uses KUMA's address from SYS → KUMA address (it works out the port by itself). In KUMA, switch on its own Wide-screen kiosk and choose where its strip sits; Dashboard fills the rest.

The mode is remembered and restored at start only while a wide screen is connected, so a laptop that is sometimes undocked is not left with a strange window. SYS → Window → Auto-fit window height to the screen additionally keeps a normal window from running off a short screen.

System: licence, files and updates

• Licence: your licence type, the seat Dashboard holds (for example seat 1 of 1), the code (partly hidden) and how long Dashboard keeps working offline. Give this seat back frees it to use on another computer.
• KUMA address: only for the Beside KUMA wide-screen mode (host and, optionally, port). Leave the port empty to find it automatically.
• Window → Auto-fit: keeps the window within a short screen.
• Configuration → Save / Load: saves everything (pages, boxes, connections, imported images, videos and fonts) into one file and loads it back. Use it as a backup and to move your dashboards to another computer.
• Releases URL / Check for updates: an optional manual check for a newer version. It only tells you; nothing is downloaded or installed by itself.

Recipes for event production

Practical set-ups, from the simplest to a full multi-screen show. The finished example dashboard in this guide is built from these pieces.

1. Stage manager's panel

Goal: one screen that tells you the time, the state and the next cue, and lets you run the show with your thumb.

1. Add Timer with progress bar and Status and cue from the KUMA presets and make the timer the largest box.
2. Add rules to the timer: red when KUMA_Timer:overtime is true, orange when KUMA_Timer:progress is below 12.
3. Add START, PAUSE and RESET boxes with Press a Companion button pointing at the KUMA buttons in Companion; add boxes for your presets (5, 10, 15 minutes) with the same action.
4. Add a cue list: five boxes with $(KUMA_Timer:cue_1_name)…cue_5_name (or build one and Repeat as series). Give each a rule that highlights it when KUMA_Timer:cue_index equals its number.
5. Lock the layout. Put the screen where the stage manager can reach it.

2. Video operator's page

1. Add program and preview tiles from the switcher's presets (or two boxes with $(atem:pgm1_input) and $(atem:pvw1_input)), with a red and a green border and a bar label PROGRAM / PREVIEW.
2. Add the KUMA timer as a thin box with a progress bar, so the operator sees the clock without leaving the page.
3. Add source buttons and CUT / AUTO / FTB with button-press actions.
4. Give the page its place in the navigation, with a Go to a page box that is shown on all pages.

3. Status wall for technicians

Open Presets… and press Add all for each connected module. Every module gets an OK / PROBLEM tile and modules with more detail (power supplies, cards) get their own tiles. Arrange them in a grid with the alignment tools. A single glance tells you which device dropped out.

4. Producer's tablet

Enable the web server, add a page drawn for the tablet's shape and open the address in the tablet's browser. Leave the password empty for a view-only status screen, or set one so the producer can also press buttons.

5. Confidence screen in the green room

Show the timer large, the running cue name and the clock on a TV or monitor through a browser in full screen. No password, no buttons, just information.

6. Several rooms, one screen

Add a connection for each Companion computer (LINK → Add connection, give each a clear name). Use the picker to pick variables from each: Dashboard writes the right alias for you. One screen can now show the main stage, the breakout room and the registration desk.

Troubleshooting

Still stuck? Write to support@kumatimer.app with a screenshot and a copy of your saved configuration file.

Tips

• Build once, then duplicate and change. Duplicating a box and using Find & replace in all rules is faster than starting over.
• Use Undo freely; use Save (SYS) before big changes.
• Name your Companion connections clearly; the names appear in the picker and in aliases.
• For readable timers: Auto-fit, bold, a high-contrast colour, and a rule for overtime.
• A progress bar behind the numbers shows how much time is left at a glance, even when you cannot read the digits.
• Keep one page per screen shape; scale the same layout up only if the screens have the same shape.

Glossary

Related: KUMA wide-screen kiosk · KUMA Companion module · Wide-screen walkthrough (blog) · Download Dashboard