Device creator

Teach Tangle a device it has no driver for - connection, commands, feedback and controls in the designer, optional code, then save and install. Share the result on the community repository.

The device creator writes a driver for a device Tangle does not know yet, without leaving the designer: say how to reach the device, what to send, how to read its answers and which controls it gets, and add code only where settings are not enough. Save and install turns it into a module on the core, ready for scenes, timelines, automations and dashboards like any bundled driver.

Open it with Device creator at the bottom of the sidebar.

#Start a driver

Pick the connection the device speaks:

Import a driver.json opens a driver made elsewhere. Your drivers lists the drivers saved on this core.

#The tabs

The editor checks the driver as you type: the number next to a tab and the Checks list say what is left to fix. Unsaved work is kept in the browser.

#Device

Manufacturer, Product or protocol and Category make the driver's id, <manufacturer>.<product>.<category> (use misc as the manufacturer for a protocol). Changing them later makes a new driver. Add the Name shown, Version, Author, Description and the Models it works with.

#Connection

The connection type and its defaults: the default port (each device sets its own address and can change the port), whether messages are Text or Bytes (hex), what ends each reply, whether the device asks for a password, the answer timeout and a pause between sends.

Device settings adds settings each device fills in (a channel, a zone), used in commands as {key}.

One driver can reach the same device in several ways, like LAN and RS-232: + Add a connection adds another one. Commands, controls and code are shared; a command can send something else on one connection, and a connection can have its own feedback rules. Each device picks its connection in its settings.

#Commands

Each command is a message template, for example PWR ON\r. Templates take escapes (\r, \n, \x02) and {name} placeholders with filters: {level|scale:0:100}, {n|hex:2}, {x|pad:3}, {src|map:hdmi1=1,hdmi2=2}. A command can wait for an answer, and the preview shows what goes on the wire.

• HTTP commands have a method, a path, headers and a body.
• OSC commands have an address (/ch/{ch|pad:2}/mix/fader) and typed arguments (int, float, string, blob, bool…); several messages can go in one bundle.
• Modbus commands write a register, read one, or run a function code.
• Runs code runs your own function from the Code tab instead of a template.

On its own picks the commands sent when the connection opens and the ones sent regularly (a status query), with the interval. Regular commands also tell Tangle the device is there.

#Feedback

Rules that read what the device sends. A rule matches each message with a regular expression (an OSC address for OSC drivers); its first group is the value. A map turns raw values into others (0=false, 1=true), and the rule sets a value of this driver, a standard state (Power, Mute, Level 0..1 with the device's range, Input, Preset) or raises an event. Try a message shows what the rules make of a message you paste.

Values of this driver are shown on the device page and can be used in controls, automations and dashboards.

Modbus drivers have a Registers tab instead: table, address, data type, byte order, scale, offset, unit and map of each register, read every poll interval.

#Controls

Standard actions maps commands to Tangle's standard actions (power on and off, mute, select input, set level, recall preset), so scenes, intents, automations and dashboards use the device like any other. Tick Assume the action worked for devices that do not report their state.

Controls adds controls for the device page and dashboards; the standard actions get theirs already.

#Code

Optional JavaScript (script.js) that runs in the driver's own process on the core, with Node.js. Start from the template gives:

export default {
  async connect(api) {},            // after the connection opens
  message(text, api, json) {},      // every message
  async poll(api) {},               // every poll interval
  actions: {                        // commands marked "Runs code"
    async login(params, api) {
      await api.request(`LOGIN ${api.config.password}\r`, { match: /^OK/ });
      api.set("loggedIn", true);
    },
  },
};

api can send, request (send and wait for a matching answer), run another command, call http, midi, modbus and osc helpers, set values, emit events, log, sleep, and read config and variant.

#Try it

After saving, add a device that uses the driver and try it here: run each command, watch the traffic in both directions and the values the feedback rules set.

#Files

Download the Module folder (.zip), a module that needs nothing else: unzip it into another core's modules folder. driver.json alone is the definition, to edit or share.

#Save and install

Save and install builds the module, installs it on this core, reloads its process and restarts the devices that use it. The driver then appears in the Driver library of every device page.

#Delete a driver

Right-click a driver under Your drivers (or use its … button, or the … button in the editor) and choose Delete driver…. Deleting uninstalls the driver's module and removes its definition and code from this core. If devices use the driver, Tangle offers to delete those devices first, showing what else goes with them. Download its driver.json from the Files tab first to keep a copy. Modules that come with Tangle are not drivers and cannot be deleted here; remove them under Settings > Modules.

Tip: Build and test a driver against the simulator before the device is on site: its ascii type answers line-based commands from rules, osc stores and answers OSC messages, and moxa.nport.gateway puts a device behind an IP-to-serial gateway. See Simulator.

#Share it on the community repository

The community repository (community.tangle.systems) is where people share the drivers they make.

1. Sign in under Settings > Community with the email and password of your Tangle license account. The first time, choose a username: it becomes your namespace, so your drivers are named <username>/<driver id>.
2. Open your saved driver in the device creator and click Publish to community. Each published version is final: publish a new version to change it.

To install someone else's driver, open the Driver library on a device page and tick Also search all community drivers. Use installs it and picks it for the device. My community drivers lists your own. A driver that does not behave can be reported from the library.

#API

• REST: /api/v1/drivers (list, get, files, check, save, delete) and /api/v1/community (status, sign-in, register, sign-out, search, install, publish).
• MCP: list_drivers, get_driver, get_driver_files, check_driver, save_driver, delete_driver and community.
• CLI: tangle-core community status and tangle-core community search [words] [--mine].
• Core finds the builder with --device-creator <dir> (default: device-creator/ next to the core program) and keeps saved drivers in its data folder under drivers/.

To write a module by hand instead, with full control of the protocol, see Module SDK.