Designer Manual

The Visual Designer is a built-in tool for creating and editing RadioKit UI layouts without writing Arduino code. It provides a drag-and-drop canvas, a property inspector, and automatic code generation.

Opening the Designer

There are two ways to open the Designer:

From the Designs tab — Tap the palette icon (+ Create) in the app bar to start a new design
From an existing design — Tap any saved design in the Designs tab to edit it
Import a file — Tap “Open” in the Designs tab app bar, then select a .h or .json file

Layout Overview

The Designer has three main areas:

[Top Bar]
[Canvas (left)] [Inspector Panel (right)]

Top Bar

The top bar contains:

Back arrow — Returns to the Designs tab (prompts to save if unsaved changes)
Project name — Tap the pencil icon to rename. Names must be valid C++ identifiers (letters, digits, underscores).
File indicator — When editing a file-linked design, shows the filename in parentheses
TEST / DONE button — Toggles Play mode for interactive testing
Undo / Redo — Step through edit history
SAVE — Appears when there are unsaved changes
SAVE AS — Export to a new file (shown when in file mode)

Canvas

The canvas is the main editing area where widgets are placed and arranged. It displays:

A grid overlay (configurable: lines, dots, or none)
All placed widgets rendered at their actual size
Selection handles on the currently selected widget
Drag handles for repositioning and resizing
A debug overlay showing widget bounds (when a widget is selected)

Interactions:

Tap a widget to select it and open the Inspector
Drag a widget to reposition it on the grid
Drag the corner handles to resize (constrained by aspect ratio where applicable)
Long press to enter multi-select mode (on canvas widgets)

Floating buttons:

+ (bottom-left) — Opens the Add Widget bottom sheet
Code icon (bottom-right) — Opens the Code Viewer (JSON + Arduino code)

Inspector Panel

The Inspector panel (right side) shows configuration options for the selected widget or the overall model. Toggle it with the “INSPECTOR” edge tab.

When no widget is selected, the Inspector shows Model Settings:

MODEL — Device name (required), description, type (Locomotive/Truck/Car/IOT), password
TRANSPORTS — Enable/disable BLE, WiFi, and Cloud transports. WiFi shows STA SSID/PASS fields. Cloud (shown only when WiFi is on) shows Account and Relay URL fields.
FEATURES — OTA firmware update toggle, Filesystem (LittleFS) toggle
CONTROL UI — Orientation (Landscape/Portrait), canvas size, grid style, skin selector
TELEMETRY — Configure up to 4 telemetry widgets with labels, icons, and units

When a widget is selected, the Inspector shows widget-specific properties (see Widget Properties below).

Adding Widgets

Tap the + FAB (bottom-left) to open the Add Widget bottom sheet. Widgets are organized into two categories:

Controls

Widget	Description
Push Button	Momentary press button (on while held)
Toggle Button	On/off toggle switch
Slide Switch	Horizontal slide toggle
Rocker Switch	Rocker-style on/off switch
Multiple Button	Row/column of mutually exclusive buttons
Multiple Select	Row/column of independently toggleable buttons
Linear Slider	Horizontal or vertical slider track
Gas Pedal	Vertical pedal-style slider
Rotary Knob	Rotary dial control
Steering Wheel	Large rotary steering control
Joystick	2-axis analog stick

Indicators

Widget	Description
Text Display	Read-only text output
Serial Monitor	Scrolling console output
LED	RGB indicator light

Tap any widget type to add it to the canvas at position (100, 100) with default size.

Common Properties

All widgets share these Inspector fields:

Label — The C++ variable name (must be a valid C++ identifier: starts with letter or underscore, contains only letters/digits/underscores)
Label Visible — Toggle the eye icon to show/hide the label on the canvas
Size — Width and height in grid units. Widgets with fixed aspect ratios show only the primary dimension.
Position — X and Y coordinates on the grid
Rotation — Angle in degrees (-180 to 180)

Button Properties

Mode — push (momentary) or toggle (on/off)
On Text — Text shown in the ON state (default: “ON”)
On Icon — Icon shown in the ON state
Off Text — Text shown in the OFF state (default: “OFF”)
Off Icon — Icon shown in the OFF state
Haptics — Enable/disable vibration feedback

Slide Switch / Rocker Switch Properties

On Text / On Icon — Display in ON state
Off Text / Off Icon — Display in OFF state
Haptics — Enable/disable vibration feedback

Slider Properties

Range — uni (0 to 100) or bi (-100 to 100)
AutoCenter — Enable spring-return to a position
- Position — min, center, or max
- Spring — smooth, elastic, or linear
- Duration — Spring animation duration in ms

Knob / Steering Wheel Properties

Center Icon — Icon displayed in the center of the knob
Range — uni or bi
Min Angle / Max Angle — Rotation limits in degrees (default: -135 to 135)
AutoCenter — Same options as Slider

Joystick Properties

AutoCenter — Enable spring-return
- Position — left, right, top, down, or center
- Spring — smooth, elastic, or linear
- Duration — Spring animation duration in ms

Multi Button / Multi Select Properties

Haptics — Enable/disable vibration feedback
Items — Number of buttons (1-8)
Direction — horizontal or vertical layout
Per-item configuration — Each item has:
- ON label (text)
- ON icon (from icon picker)
- OFF label (text)
- OFF icon (from icon picker)

LED Properties

State — off, on, blink, or breathe
Shape — circle, square, diamond, or star
Timing — Animation timing in ms

Text Display Properties

Text — Display string
Font Size — Text size in pixels
Font Family — monospace, sans-serif, or serif

Serial Monitor Properties

Font Size — Console text size
Font Family — monospace, sans-serif, or serif

Play Mode

Tap TEST in the top bar to enter Play mode. In Play mode:

The canvas renders widgets as they would appear in the control screen
Widgets are interactive (you can press buttons, drag sliders, etc.)
The Inspector panel is hidden
The Add Widget FAB is hidden
Widget interactions send values to the connected device (if connected)

Tap DONE to return to edit mode.

Code Viewer

Tap the Code icon (bottom-right FAB) to open the Code Viewer. It shows a dual-pane view:

Left pane — UI Config (JSON): The complete designer JSON configuration. This is the source of truth for the layout.

Right pane — Arduino Code: Generated C++ header code ready to copy into your Arduino sketch.

Actions:

COPY — Copy the complete RadioKit_UI.h file to clipboard
SHARE — Share the file via the system share sheet
.h — Download the generated header file
Close — Return to the canvas

JSON Config Format

The designer serializes layouts to a standardized JSON format:

{
  "version": 1,
  "config": {
    "name": "MyController",
    "description": "Robot controller",
    "orientation": "landscape",
    "theme": "DRAGON",
    "password": "",
    "type": "Locomotive",
    "transports": {
      "ble": { "enabled": true },
      "wifi": { "enabled": false, "ssid": "", "pass": "" },
      "cloud": { "enabled": false, "account": "", "relay": "" }
    }
  },
  "features": {
    "ota": false,
    "filesystem": false
  },
  "canvas": {
    "size": [200, 100],
    "gridStyle": "lines"
  },
  "widgets": [
    {
      "type": "slider",
      "name": "throttle",
      "position": [10, 20, 0],
      "size": [80, 12],
      "properties": {
        "min": -100,
        "max": 100,
        "autoCenter": ["center", "smooth", 300]
      },
      "label": { "text": "Throttle", "show": true }
    }
  ],
  "telemetry": [
    { "label": "battery", "icon": "battery", "unit": "%" }
  ]
}

Generated Arduino Code

The code generator produces a complete .h file with:

#define directives for enabled transports (e.g. #define ENABLE_RK_BLE) at the top, before #include <RadioKitLib.h>
A JSON config comment block (for re-import)
Widget declarations matching the designer layout
A setup() function with conditional transport start calls under #ifdef guards
Proper positioning, sizing, and variant configuration

The generated code can be included directly in your Arduino sketch with #include "RadioKit_UI.h".

Transport #define pattern:

#define ENABLE_RK_SERIAL  // always on
#define ENABLE_RK_BLE
// #define ENABLE_RK_WIFI   // commented out when disabled
// #define ENABLE_RK_CLOUD  // commented out when disabled

#include <RadioKitLib.h>

Serial is always enabled. Comment out #define ENABLE_RK_SERIAL manually to disable it.

Import and Export

Import from File

From the Designs tab, tap “Open” to import:

.h files — Extracts the JSON config from the comment block
.json files — Loads the raw JSON directly

Export to File

From the Code Viewer:

COPY — Copy the complete file to clipboard for pasting into your project
.h — Download as a .h file
SAVE AS — Save to a specific location on the filesystem

Save to App Storage

Tap SAVE in the top bar to save the current design to the app’s local storage. Saved designs appear in the Designs tab.

Undo / Redo

The Designer maintains a full edit history. Use the undo/redo buttons in the top bar to step through changes. Every property change, widget addition, deletion, and repositioning is tracked.

Skin Preview

The canvas renders widgets using the currently selected skin. Change the skin in the Inspector under CONTROL UI > Skin. Available skins:

dragon — Industrial orange (default)
neon — Cyberpunk cyan
minimal — Clean white
custom — User-defined colors

The skin only affects the designer preview. The actual device UI uses whatever skin is configured in the Arduino code.

File Mode vs App Mode

Designs can be stored in two ways:

App mode — The design is stored as JSON in the app’s local database. Changes are saved with the SAVE button.

File mode — The design is linked to a .h or .json file on the filesystem. Saving writes directly to the original file. Use SAVE AS to create a copy at a different location.

When opening a file-linked design, the filename is shown in the top bar next to the project name.

Tips

Name your widgets — Use descriptive C++ identifiers (e.g., throttle, fire_button, speed_display) instead of defaults
Use aspect ratios — Widgets like sliders and multi-buttons have fixed aspect ratios. Only adjust the primary dimension.
Test in Play mode — Switch to TEST mode frequently to verify layout and interaction before exporting
Start with a demo — Open an existing design or demo configuration as a starting point
Check the JSON — The Code Viewer’s JSON pane shows the exact configuration. Compare with the Arduino protocol for advanced customization.