Programmable D3.js charts

From an agent value to a browser visualization

Create your first D3JS Chart

Choose the strategy that matches how data changes

The object returned by the chart script

The context object supplies d3, container, environmentUuid, thingUuid, channel, component options, and a per-browser stateManager. The state manager exposes loadRawState() and saveRawState(state).

CPU and memory gauge from chart-template.js

The supplied template calls the built-in System Monitor Thing, converts its CPU ratio and memory counters into percentages, and draws two needles over green, amber, and red utilization zones. This abridged excerpt preserves the template's essential data path:

return {
    config: {
        systemMonitorThingUuid: '00000000-0000-0000-0000-000000000010',
        zones: [
            {from: 0, to: 60, color: '#22c55e'},
            {from: 60, to: 80, color: '#f59e0b'},
            {from: 80, to: 100, color: '#ef4444'}
        ]
    },

    init(context) {
        this.svg = context.d3.select(context.container)
            .append('svg')
            .attr('width', '100%')
            .attr('height', '100%');
    },

    async poll(channel) {
        const result = await channel.thingApiCall(
            this.config.systemMonitorThingUuid,
            {method: 'readState'}
        );
        return result.response;
    },

    convert(rawData) {
        const total = Number(rawData.ram.totalMemorySize);
        const free = Number(rawData.ram.freeMemorySize);
        return [
            {label: 'CPU', value: Number(rawData.cpu.cpuLoad) * 100},
            {label: 'Memory', value: total > 0 ? ((total - free) / total) * 100 : 0}
        ];
    },

    render(data, context) {
        const d3 = context.d3;
        const angle = d3.scaleLinear().domain([0, 100]).range([-90, 90]);
        // The complete template draws zones, ticks, two needles and value labels.
        // Keep persistent elements on this object when later updates must reuse them.
    },

    destroy() {
        this.svg?.remove();
        this.svg = null;
    }
};

Adapting it to another Thing

1. Put the target component UUID in config.
2. Change the method and parameters passed to channel.thingApiCall().
3. Inspect result.response and make convert() return a stable, simple chart model.
4. Bind that model to D3 selections in render(). Handle repeated calls and container resizing rather than assuming a single render.

Subscribe without polling

Select ASYNC_EVENTS and declare precise filters. Replace the example values with the source node UUID and the fully qualified event type delivered by your environment.

return {
    subscriptions: [{
        nodeUuid: 'SOURCE-COMPONENT-UUID',
        eventType: 'com.example.SensorStateEvent'
    }],

    convert(event) {
        return {value: Number(event.value), timestamp: event.timestamp};
    },

    render(data, context) {
        // Update the D3 visualization with the converted event.
    }
};

Load history once, then append live events

With ONE_TIME_LOAD_AND_ASYNC_EVENTS, the component establishes event subscriptions first and then invokes poll() once. poll() should return the stored historical collection; onEvent() should normalize and append each later event. The component coordinates the two deliveries but does not merge their payloads automatically. The Refresh button can repeat the history request without enabling periodic polling.

return {
    subscriptions: [{
        nodeUuid: 'SOURCE-COMPONENT-UUID',
        eventType: 'com.example.SensorStateEvent'
    }],

    async poll(channel) {
        this.historyLoading = true;
        try {
            const result = await channel.thingApiCall(
                'HISTORY-STORAGE-THING-UUID',
                {method: 'readHistory'}
            );
            return result.response;
        } catch (error) {
            this.historyLoading = false;
            throw error;
        }
    },

    convert(rawData) {
        const items = Array.isArray(rawData) ? rawData : [rawData];
        return items.map(item => ({
            timestamp: new Date(item.timestamp),
            value: Number(item.value)
        }));
    },

    render(history, context) {
        // A new array means an initial or manually refreshed history snapshot.
        // Preserve events that arrived while the initial history request was running.
        if (history !== this.historySnapshot) {
            const pending = this.pendingPoints ?? [];
            this.historySnapshot = history;
            this.points = [...history, ...pending];
            this.pendingPoints = [];
        }
        this.historyLoading = false;
        this.draw(this.points, context);
    },

    onEvent(event, context) {
        const [point] = this.convert(event);
        if (point) {
            if (this.historyLoading || this.historySnapshot === undefined) {
                this.pendingPoints ??= [];
                this.pendingPoints.push(point);
            } else {
                this.points.push(point);
                this.draw(this.points, context);
            }
        }
    },

    draw(points, context) {
        // Apply the normal D3 data join and redraw axes or paths here.
    }
};

The browser editor uses these methods automatically. Read operations require component read permission; updating the script requires update permission.