@linuxcnc-node/hal/dist/component.d.ts

Node.js bindings for LinuxCNC HAL library

import { EventEmitter } from "events";
import type { HalType, HalPinDir, HalParamDir, HalValue } from "@linuxcnc-node/types";
import { Pin, Param } from "./item";
/** Default polling interval in milliseconds for monitoring value changes */
export declare const DEFAULT_POLL_INTERVAL = 10;
/**
 * Delta update structure for HAL items.
 * Contains all items that changed in a single polling cycle.
 */
export interface HalDelta {
    /** Changed items as flat array of name-value pairs */
    changes: Array<{
        name: string;
        value: HalValue;
    }>;
    /** Monotonic cursor for sync verification */
    cursor: number;
    /** Timestamp of update (ms since epoch) */
    timestamp: number;
}
/**
 * Events emitted by HalComponent.
 */
interface HalComponentEvents {
    /** Emitted when one or more items change during a polling cycle */
    delta: [delta: HalDelta];
}
/**
 * Configuration options for the monitoring system.
 */
export interface HalMonitorOptions {
    /** Polling interval in milliseconds (default: 10) */
    pollInterval?: number;
}
export interface NativeHalComponent {
    newPin(nameSuffix: string, type: number, direction: number): boolean;
    newParam(nameSuffix: string, type: number, direction: number): boolean;
    ready(): void;
    unready(): void;
    getProperty(name: string): HalValue;
    setProperty(name: string, value: HalValue): HalValue;
    readonly name: string;
    readonly prefix: string;
}
/**
 * Represents a HAL component.
 *
 * This class provides functionality to create HAL components, pins, parameters,
 * and interact with the HAL environment.
 *
 * @example
 * ```typescript
 * const comp = new HalComponent("my-component");
 * const pin = comp.newPin("output", "float", "out");
 * comp.ready();
 * pin.setValue(123.45);
 *
 * // Listen for value changes
 * pin.on('change', (newVal, oldVal) => {
 *   console.log(`Changed: ${oldVal} -> ${newVal}`);
 * });
 *
 * // Listen for batch delta updates
 * comp.on('delta', (delta) => {
 *   console.log(`${delta.changes.length} items changed at cursor ${delta.cursor}`);
 * });
 * ```
 */
export declare class HalComponent extends EventEmitter<HalComponentEvents> {
    private nativeInstance;
    private pins;
    private params;
    private watchedItems;
    private monitoringTimer;
    private monitoringOptions;
    /** Monotonic cursor incremented on each batch update */
    private cursor;
    /**
     * The name of the HAL component (e.g., "my-js-comp")
     */
    readonly name: string;
    /**
     * The prefix used for this component's pins and parameters.
     * Defaults to the component name if not specified.
     */
    readonly prefix: string;
    /**
     * Creates a new HAL component.
     *
     * @param name - The name of the component (e.g., "my-component").
     *               This will be registered with LinuxCNC HAL.
     * @param prefix - Optional prefix for pins and parameters created by this component.
     *                 If not provided, defaults to `name`.
     */
    constructor(name: string, prefix?: string);
    /**
     * Checks if a HAL component with the given name exists in the system.
     *
     * @param name - The component name (e.g., "halui", "my-custom-comp").
     * @returns `true` if the component exists, `false` otherwise.
     */
    static exists(name: string): boolean;
    /**
     * Checks if the HAL component with the given name has been marked as ready.
     *
     * @param name - The component name.
     * @returns `true` if the component exists and is ready, `false` otherwise.
     */
    static isReady(name: string): boolean;
    /**
     * Gets the value of a pin or parameter by name.
     *
     * @param name - The nameSuffix of the pin or parameter.
     * @returns The current value.
     */
    getValue(name: string): HalValue;
    /**
     * Sets the value of a pin or parameter by name.
     *
     * @param name - The nameSuffix of the pin or parameter.
     * @param value - The value to set.
     * @returns The value that was set.
     */
    setValue(name: string, value: HalValue): HalValue;
    /**
     * Creates a new HAL pin associated with this component.
     *
     * This method can only be called before `ready()` or after `unready()`.
     *
     * @param nameSuffix - The suffix for the pin name (e.g., "in1", "motor.0.pos").
     *                     The full HAL name will be `this.prefix + "." + nameSuffix`.
     * @param type - The data type of the pin (e.g., `"float"`, `"bit"`).
     *               See {@link HalType} for available types.
     * @param direction - The direction of the pin (e.g., `"in"`, `"out"`, `"io"`).
     *                    See {@link HalPinDir} for available directions.
     * @returns A new `Pin` object instance.
     * @throws Error if component is ready or if pin creation fails.
     */
    newPin(nameSuffix: string, type: HalType, direction: HalPinDir): Pin;
    /**
     * Creates a new HAL parameter associated with this component.
     *
     * This method can only be called before `ready()` or after `unready()`.
     *
     * @param nameSuffix - The suffix for the parameter name.
     *                     The full HAL name will be `this.prefix + "." + nameSuffix`.
     * @param type - The data type of the parameter. See {@link HalType} for available types.
     * @param direction - The writability of the parameter (`"ro"` for read-only,
     *                    `"rw"` for read-write). See {@link HalParamDir}.
     * @returns A new `Param` object instance.
     * @throws Error if component is ready or if parameter creation fails.
     */
    newParam(nameSuffix: string, type: HalType, direction: HalParamDir): Param;
    /**
     * Sets up auto-watch listeners for a pin or param.
     * @private
     */
    private setupItemListeners;
    /**
     * Marks this component as ready and available to the HAL system.
     *
     * Once ready, pins can be linked, and parameters can be accessed by other
     * HAL components or tools. Pins and parameters cannot be added after `ready()`
     * is called, unless `unready()` is called first.
     */
    ready(): void;
    /**
     * Marks this component as not ready, allowing addition of more pins or parameters.
     *
     * `ready()` must be called again to make the component (and any new items)
     * available to HAL.
     */
    unready(): void;
    /**
     * Retrieves a map of all `Pin` objects created for this component.
     *
     * @returns An object where keys are the `nameSuffix` of the pins and values
     *          are the corresponding `Pin` instances.
     */
    getPins(): {
        [key: string]: Pin;
    };
    /**
     * Retrieves a map of all `Param` objects created for this component.
     *
     * @returns An object where keys are the `nameSuffix` of the parameters and
     *          values are the corresponding `Param` instances.
     */
    getParams(): {
        [key: string]: Param;
    };
    /**
     * Gets a pin by name.
     *
     * @param name - The nameSuffix of the pin.
     * @returns The Pin instance, or undefined if not found.
     */
    getPin(name: string): Pin | undefined;
    /**
     * Gets a param by name.
     *
     * @param name - The nameSuffix of the param.
     * @returns The Param instance, or undefined if not found.
     */
    getParam(name: string): Param | undefined;
    /**
     * Gets the current cursor value for sync operations.
     *
     * The cursor is monotonically increasing and increments with each delta emit.
     *
     * @returns The current cursor value.
     */
    getCursor(): number;
    /**
     * Gets a snapshot of all current item values.
     *
     * Useful for initial sync or resync after cursor mismatch.
     *
     * @returns Object with items map, current cursor, and timestamp.
     */
    getSnapshot(): {
        items: Record<string, HalValue>;
        cursor: number;
        timestamp: number;
    };
    /**
     * Configures the monitoring system settings.
     *
     * The monitoring system will check for value changes at the specified interval.
     *
     * @param options - Configuration object with `pollInterval` property (in milliseconds).
     *                  Default polling interval is 10ms.
     */
    setMonitoringOptions(options: HalMonitorOptions): void;
    /**
     * Retrieves the current monitoring configuration.
     *
     * @returns A copy of the current monitoring options.
     */
    getMonitoringOptions(): HalMonitorOptions;
    /**
     * Starts the monitoring timer if not already running.
     * @private
     */
    private ensureMonitoring;
    /**
     * Stops monitoring if no items are being watched.
     * @private
     */
    private checkStopMonitoring;
    /**
     * Starts the monitoring timer.
     * @private
     */
    private startMonitoring;
    /**
     * Stops the monitoring timer.
     * @private
     */
    private stopMonitoring;
    /**
     * Checks all watched items for value changes and emits events.
     *
     * Emits individual 'change' events on each HalItem, plus a batch 'delta'
     * event on the component with all changes aggregated.
     * @private
     */
    private checkForChanges;
    /**
     * Cleans up the component, stops monitoring and removes all listeners.
     *
     * Should be called when the component is no longer needed to prevent memory leaks.
     */
    dispose(): void;
}
export {};