Omni Link — Product & Developer Documentation

1. Introduction

2. Quick Overview

After registration, Omni Link opens in deployment mode—the clean, end-user interface. To switch into edit mode where you can build and configure your agent, click the top-left icon and enter the default password: omnilink (We’ll cover how to change this password and secure your agent later in the Security section.)

3. Use Cases

Omni Link adapts to environments ranging from individual homes to complex industrial floors. Below are two flagship scenarios that show how natural language control becomes reliable, safe action.

4. Quickstart

You are an agent who helps customers choose the best country to visit and arranges their travel based on their preferred mode of transportation.

book_flight_ticket_to_[country],
book_train_ticket_to_[country]

# Clone the example repo
git clone https://github.com/omni-link-tech/omni-link-travel-agent.git

cd omni-link-travel-agent

5. Architecture

Explore the Omni Link stack through the interactive diagram below. Click each component to see how agents, the OmniLink engine, transport bridges, and targets exchange commands, context, and feedback.

6. Agent Configuration

This section covers how to customize your agent.

• Main Task: The main task is the overall goal of your agent. It should be written as a general description that combines everything the agent needs to do.
  Example:

You are a hotel customer service agent who manages reservations and answers customer questions.

• Commands: Define patterns that map human-friendly input to structured commands. These should be descriptive phrases separated by underscores.
  Example:

book_room_number_1

But if you have 100 rooms, creating 100 commands is impractical. Instead, use variables inside square brackets:

book_room_number_[number]

Anything inside [] will be treated by the agent as a variable. You just have to describe the type of variable.
Example:

turn_on_light_in_[room]

• Custom Instructions: Write the rules your agent must follow.
  Example: Always ask the user for confirmation before executing a command.
• Knowledge: You can upload a file that will be treated as the knowledge base of the agent. This enriches the agent’s ability to answer questions and perform tasks.
• Conversation History Limit: Define how many previous exchanges the agent remembers when generating responses.

7. Command Parsing

Command parsing is the step where Omni Link converts a free-form utterance into a normalized payload that downstream systems can understand. You describe the shape of a command with a template, and the engine extracts the variables that appear between square brackets.

Here is a simple template for moving chess pieces:

move_[color]_[piece]_from_[location1]_to_[location2]

If you say: “Move the white knight from a2 to a3”, the engine extracts:

{
  "template": "move_[color]_[piece]_from_[location1]_to_[location2]",
  "vars": {
    "color": "white",
    "piece": "knight",
    "location1": "a2",
    "location2": "a3"
  }
}

This structured payload is then published to your chosen transport.

Templates can be as expressive as you need. The parser recognizes separator characters (underscores, hyphens, whitespace) and uses them to match the relevant segments. You can also add aliases for natural language variations through the <synonyms> attribute in the configuration UI.

Multiple Commands, One Template

A single template can capture a family of commands. For example, the following template handles several thermostat actions:

thermostat_[action]_to_[temperature]_degrees

Sample utterances and the extracted payloads:

// "Thermostat set to 72 degrees"
{
  "template": "thermostat_[action]_to_[temperature]_degrees",
  "vars": {
    "action": "set",
    "temperature": "72"
  }
}

// "Thermostat boost to 25 degrees"
{
  "template": "thermostat_[action]_to_[temperature]_degrees",
  "vars": {
    "action": "boost",
    "temperature": "25"
  }
}

Because both commands share the same structure, you can implement downstream logic that switches on the action variable without redefining multiple templates.

Optional Segments and Defaults

Add optional suffixes by chaining multiple templates. For example, you might support both open_[door] and open_[door]_for_[duration]_seconds. When the shorter version is triggered, your connector can provide a default duration before the door automatically closes.

Defaults can also be injected by the transport bridge. If a user omits a variable, use your connector to supply a fallback value so that the receiving device always receives a complete payload.

Using Synonyms

Natural language is messy. Pair your templates with synonym tables to map phrases such as “turn on”, “enable”, or “activate” to the same [action] variable. Here is a short example:

light_[action]_in_[room]

// With synonyms: enable → on, activate → on, kill → off
// "Activate the lights in the kitchen"
{
  "template": "light_[action]_in_[room]",
  "vars": {
    "action": "on",
    "room": "kitchen"
  }
}

The parser resolves the synonym before delivering the payload, which keeps your downstream logic consistent regardless of how the user phrased the request.

Validation Tips

• Define guard rails in your connector to reject commands with missing or malformed variables.
• Log the raw utterance alongside the parsed payload to help diagnose template gaps.
• Use the debug console to replay commands and fine-tune the template patterns before deploying to production.

By combining expressive templates, synonym mappings, and validation, you can cover the majority of natural language variations while keeping the command contract deterministic for any automation stack.

8. Agent Connection

Omni Link communicates with your automation stack through a unified connection layer. Regardless of the transport you choose, the agent always emits the same contract: command → feedback → context. This section explains how to take advantage of the connection system in both local experiments and remote deployments.

Local vs. Remote Connection

Local Connection

• Perfect for development and debugging when everything runs on the same machine or LAN.
• Run your API connector (for example link.py) locally and point the Omni Link UI to ws://localhost:9001 or mqtt://localhost:1883, depending on your transport.
• Keep the debug window open to watch the command payloads in real time before they reach your hardware or services.

Remote Connection

• Use this when the agent and the automation targets live in different networks (cloud deployment, on-prem controllers, or hybrid setups).
• Expose your broker or bridge endpoints over the internet with TLS (WSS/HTTPS) and authentication. Reverse proxies such as Nginx or Traefik help terminate certificates and enforce IP allowlists.
• Synchronize environment variables in the Omni Link UI with the remote hostnames, ports, and credentials for your broker or HTTP/WebSocket services.

MQTT Communication

MQTT is the recommended transport for mission-critical automations because it supports pub/sub semantics and lightweight payloads. Omni Link uses the following topics by default:

• olink/commands – outbound commands published by the agent.
• olink/commands_feedback – acknowledgements and execution results from your services.
• olink/context – state updates that keep users informed.

Configure Quality of Service (QoS) according to your needs. QoS 1 ensures that every command is delivered at least once, while QoS 2 guarantees exactly-once delivery for sensitive actions. Retained messages on olink/context help late subscribers catch up with the latest status.

Setting Up Mosquitto

1. Install Mosquitto: use your package manager (sudo apt install mosquitto mosquitto-clients) or Docker (docker run -p 1883:1883 -p 9001:9001 eclipse-mosquitto).
2. Enable WebSockets: update /etc/mosquitto/conf.d/olink.conf (or the Docker-mounted configuration) with:

   listener 1883 0.0.0.0
   protocol mqtt
   
   listener 9001 0.0.0.0
   protocol websockets
   
   allow_anonymous false
   password_file /etc/mosquitto/passwords
               

3. Create credentials: sudo mosquitto_passwd -c /etc/mosquitto/passwords omni-link, then restart the broker (sudo systemctl restart mosquitto or restart the container).
4. Verify connectivity: publish and subscribe using mosquitto_pub and mosquitto_sub or connect through the Omni Link UI.

For remote deployments, secure Mosquitto further with TLS certificates, unique user accounts per service, and network firewalls.

Other Connection Options

• HTTP Bridge: send POST requests with command payloads for systems that prefer synchronous workflows.
• WebSocket Bridge: maintain a persistent duplex channel ideal for browser-based clients and dashboards.
• Custom Transports: extend the connection layer by adapting the command contract to your protocol (serial, gRPC, OPC-UA, etc.).

9. Context System

Give the agent a running description of the system it controls by publishing readable context messages. Provide the state as plain text so the LLM can interpret it the same way a human operator would.

Include the most relevant details—status, recent actions, or sensor readings—in sentences or short bullet points. This keeps the agent grounded without forcing it to decipher raw data dumps.

Example context payload:

{
  "context": "Robot arm is homed. Current task: assemble panel A. Last command succeeded at 14:32."
}

Publish these updates on olink/context whenever the system changes so the user stays informed. Longer payloads are also supported as long as they remain human-readable. Below are two expanded examples that keep the model grounded without overwhelming it with noise.

Manufacturing Line Example

{
  "context": "Assembly Line 3: Conveyor speed 1.2 m/s. Robot arm completed weld sequence at 15:02 and is waiting for the next chassis. Safety gate closed. QA camera flagged Panel B for manual inspection (scratched surface)."
}

This message blends operational metrics, recent actions, and follow-up requirements. The agent can reference it to justify pausing the line, dispatching a technician, or notifying quality control without asking the operator to repeat known details.

Smart Building Example

{
  "context": "HQ Lobby: Temperature 22.3°C, humidity 46%. Front desk kiosk rebooted at 09:14 after firmware update. Visitor traffic light; no VIP guests expected this hour. Security notified about a propped door on Level 2 Stairwell B."
}

Context streams like this give conversational agents enough situational awareness to answer questions such as "Why is the stairwell alarm active?" or "Is the lobby comfortable for visitors?" while still fitting in a single MQTT payload.

10. OmniLink Engine

The omnilink.py module is the heart of the automation stack. It provides a pattern-driven command engine, adapters, and background services that let natural language requests flow to physical or digital targets safely. Drop it into any Python project to bridge commands from MQTT, TCP sockets, or remote APIs into your own handler logic.

Install the engine package with pip install omnilink-lib to start integrating it into your Python environment.

Core engine

• Template matching: The TypeRegistry and CompiledPattern helpers let you author readable command templates (for example, move_[color]_[piece]_from_[from]_to_[to]) and convert captured values into typed Python data automatically.
• Routing workflow: OmniLinkEngine stores middleware, history, and metrics. Use engine.before(), engine.after(), and engine.on() to attach auditing, validation, and business logic without scattering boilerplate throughout your app.
• Pattern utilities: load_patterns_from_file() reads plain-text templates, supports comments, and resolves relative paths, so ops teams can update command grammars without touching code.

Remote connectivity

• Supabase polling: RemoteCommandClient and OmniLinkRemoteCommandBridge watch the Omni Link cloud queue, run commands through the engine, then persist JSON responses back to the dashboard.
• TCP adapter: OmniLinkTCPAdapter forwards structured payloads to legacy control systems that expect socket messages. Environment variables customize host, port, delimiter, and logging.
• MQTT bridge: OmniLinkMQTTBridge subscribes to olink/commands, executes them through the engine, and publishes feedback plus optional context updates via give_context() and the periodic context helpers.

Example: File-backed templates with MQTT bridge

The following link_mqtt.py sample combines template loading, a catch-all handler, and the MQTT bridge into a single deployment script:

from pathlib import Path
import os
from omnilink import (
    TypeRegistry,
    OmniLinkEngine,
    OmniLinkMQTTBridge,
    load_patterns_from_file,
    give_context,
    start_periodic_context,
)
from project_api import get_context

HERE = Path(__file__).resolve().parent
PATTERNS_FILE = HERE / "commands_omnilink.txt"

types = TypeRegistry()
TEMPLATES = load_patterns_from_file(PATTERNS_FILE, types)
engine = OmniLinkEngine(TEMPLATES, types=types)


def handle_any(evt):
    print("[link] EVENT matched -> template:", evt["template"], "vars:", evt["vars"])
    v = evt.get("vars", {})
    try:
        color      = v["color"]
        piece      = v["piece"]
        location1  = v["location1"]
        location2  = v["location2"]

    except KeyError as e:
        return {"ack": False}


    return {"ack": True}

engine.on(lambda e: True, handle_any)

bridge = OmniLinkMQTTBridge(engine)

start_periodic_context(30, lambda: get_context(full=True))

bridge.loop_forever()

Imports: Pull core engine classes, the pattern loader, and context helpers from omnilink. The local project_api.get_context keeps your telemetry or status feeds in one place while Path resolves template files relative to the script.

Template loading: TypeRegistry() defines reusable converters (for example, square → chess coordinates). load_patterns_from_file() reads commands_omnilink.txt, compiles each pattern with the registry, and returns a ready-to-run template list for OmniLinkEngine.

Catch-all handler: The handle_any() function logs the matched template and pulls variables from each event. If a required value is missing, it returns {"ack": False}; otherwise it acknowledges the command. The engine.on(lambda e: True, handle_any) registration ensures this logic runs for every event, giving you a default safety net before layering in more specific handlers.

MQTT bridge + context loop: OmniLinkMQTTBridge binds the engine to your olink/commands topic. start_periodic_context(30, ...) pushes fresh context messages every 30 seconds via give_context() so agents stay aware of the latest state. Finally, bridge.loop_forever() enters the MQTT network loop and keeps the script running.

The module stays optional—import only the pieces you need. For a minimal deployment, instantiate OmniLinkEngine with your templates, register handlers, and start the MQTT bridge to begin receiving commands immediately. Scale up by layering remote polling or TCP forwarding as your environment evolves.

11. Tutorials

• Chess Demo: Full GitHub project (omni-link-tech/omni-link-chess). Demonstrates command parsing, context updates, and UI sync.
• Travel Agent Demo: (explained above) shows how to build a conversational API connector.
• Smart Home Demo: Coming soon.

12. Security

Omni Link ships with the default edit-mode password omnilink. Before you deploy an agent for others to use, open Settings → Security, set a new password, and share it only with trusted collaborators. This password controls access to edit mode, so rotating it regularly keeps your deployment safe.

The password is global across all agents.

If you are the developer of the agent, please don't give the app password to any of your users, as they can then change the agent's configuration and alter its behavior. It is always best practice to add one more safety layer in your system to verify the commands coming from the agent.

13. Usage Management

Here we will discuss how to optimize your usage to get the best value out of your agent for the credits you have.

You can check your current usage by opening the Usage page in the side menu.

For the AI processing part, the more intelligent you make your agent the more tokens it is going to consume. When you add a long knowledge file, long context, or update the context frequently, all of this consumes tokens.

Best practice: during development, set the agent to respond in text only. Enable voice responses later for final testing and demos. This keeps token consumption efficient.

14. FAQ

Q: Can I run Omni Link fully offline?
Yes. Use only the local broker and disable cloud sync.

Q: Does it support multiple languages?
Yes. Configure your language in Settings → Language.

Q: How do I add new commands?
Simply edit your templates in Settings → Commands and restart the bridge.

Q: What should I do if I forget my edit-mode password?
You can reset it from Settings → Security while authenticated, or ask a teammate with access to update it.

Q: Can multiple teammates collaborate on the same agent?
Absolutely. Share the edit-mode password with trusted collaborators so they can sign in and contribute in real time.

Q: Where can I monitor system status and incidents?
Visit the Status page from the side navigation to review uptime history and subscribe to notifications.