Skip to main content

Script Console

The Script Console provides an interactive JavaScript editor for running scripts directly on the GEM server or in the browser client. It is useful for debugging, testing, querying data, and performing one-off administrative tasks.

Overview​

The console features a split-panel layout:

  • Left Panel: Code editor with syntax highlighting and AI assistance
  • Right Panel: Output console showing script results, logs, and errors

Target Selection​

Scripts can run in two environments:

Server Target​

  • Executes JavaScript on the GEM Node.js backend
  • Has access to server-side APIs, database, device drivers, and system resources
  • Console output (console.log, console.error, etc.) is captured and returned
  • Useful for database queries, device operations, and system diagnostics

Client Target​

  • Executes JavaScript in the browser
  • Has access to window.gem (the GemApp singleton)
  • Console methods are temporarily intercepted to capture output
  • Useful for testing UI API calls and frontend logic
  • Can target the local browser or a remote connected client

Remote Client Execution​

When the Client target is selected, a Client dropdown appears listing all currently connected UI clients (excluding the current browser). Each entry shows the client's IP address and user agent.

  • Select a client from the dropdown to run the script on that remote browser
  • Leave the dropdown empty (placeholder: "this browser") to run locally
  • The client list refreshes automatically every 5 seconds
  • Remote scripts have access to the gem (GemApp) instance on the target client
  • Console output from the remote client is captured and returned to the output panel
note

Remote clients must be connected and reachable. If a target client disconnects before the script completes, a timeout or error will be returned.

Using the Console​

  1. Select a Target (Server or Client)
  2. If Client is selected, optionally choose a remote client from the dropdown
  3. Write JavaScript in the editor panel
  4. Click Run (or use the keyboard shortcut)
  5. View results in the output panel

Output Panel​

Output lines are color-coded by type:

  • Log (white) - Standard console.log output
  • Info (blue) - console.info messages and status updates
  • Warn (yellow) - console.warn messages
  • Error (red) - Errors and console.error messages
  • Result (green) - Return values from the script

Each line includes a timestamp. Click Clear to reset the output panel.

Editor Features​

The script editor provides:

  • Syntax highlighting for JavaScript
  • Search and replace (Ctrl+F / Ctrl+H)
  • Code formatting (Ctrl+Shift+B)
  • Status bar showing cursor position (line, column)
  • Auto-complete for GemApp / GemServer methods
  • AI assistant integration (when configured)
  • Auto-save disabled by default (scripts are ephemeral)
  • Script type adapts to the selected target

Example Scripts​

Server: Query Devices​

let Data = GemServer.getInstance().data;
let devices = await Data.query('device', {enabled: true});
console.log('enabled devices:', devices.length);
for (let d of devices) {
    console.log(`  ${d.name} - ${d.driver} - ${d.address}`);
}

Server: Check Zone States​

let Data = GemServer.getInstance().data;
let zones = await Data.query('zone', {subsystem_id: 1});
for (let z of zones) {
    let attrs = await Data.getAttributes('zone', z.id);
    console.log(`${z.name}: level=${attrs.level}, state=${attrs.state}`);
}

Server: Read System Variables​

let srv = GemServer.getInstance();
let sunset = await srv.getVariable('sunset');
console.log('sunset:', sunset);

// Read a secure (encrypted) variable
let apiKey = await srv.getVariable('my_api_key', true);
console.log('api key:', apiKey);

Client: Test API Call​

let devices = await gem.query('device', {enabled: true});
console.log('devices:', devices.length);
devices.forEach(d => console.log(d.name, d.driver));

Client: Send Command​

let result = await gem.command({
    device_id: 1,
    action: 'on',
    level: 100
});
console.log('command result:', result);

Security Considerations​

  • Script Console requires the admin role — users without the admin role will receive an authorization error
  • Server-side scripts execute with full system privileges
  • Remote client scripts execute with the privileges of the target client's authenticated user
  • Avoid running untrusted scripts
  • Scripts do not persist between sessions unless explicitly saved