@adcops/autocore-react 3.3.9 → 3.3.10

package/src/hooks/adsHooks.tsx

@@ -1,287 +1,287 @@
-/*
- * Copyright (C) 2024 Automated Design Corp.. All Rights Reserved.
- * Created Date: 2024-04-26 09:04:40
- * -----
- * Last Modified: 2026-01-29 09:33:22
- * -----
- * 
- */
-
-
-
-import { useContext, useRef, useEffect, useCallback } from 'react';
-import { EventEmitterContext } from '../core/EventEmitterContext';
-import { MessageType } from '../hub/CommandMessage';
-
-
-/**
- * Sleep for a given number of milliseconds.
- * @param ms Number of milliseconds to sleep.
- */
-function sleep(ms: number): Promise<void> {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-
-
-
-/**
- * Custom hook for registering symbols and subscribing to updates on the 
- * ADS domain via the EventEmitterContext.
- * This hook abstracts the common pattern of registering symbols and handling subscriptions
- * to updates in components that need real-time data from a backend service.
- *
- * @param setters A mapping of state setter functions, where each key corresponds to a piece of state
- *                related to a symbol, and each value is the setter function for that state.
- * @param symbols A mapping of state keys to their corresponding symbol names in the backend system.
- *                Each key should match a key in the `setters` object, and each value should be a string
- *                that represents the symbol name to register and subscribe to.
- *
- * ## Usage Example:
- * ```typescript
- * const setters = {
- *     speed: setSpeed,
- *     temperature: setTemperature
- * };
- *
- * const symbols = {
- *     speed: "Sensor.speed",
- *     temperature: "Sensor.temperature"
- * };
- *
- * useRegisterSymbols(setters, symbols);
- * ```
- *
- * This will register and subscribe to updates for "Sensor.speed" and "Sensor.temperature",
- * and update the `speed` and `temperature` states via `setSpeed` and `setTemperature` respectively
- * whenever new data is received.
- */
-export const useAdsRegisterSymbols = (
-    setters: Record<string, (value: any) => void>, 
-    symbols: Record<string, string>,
-    options: Record<string, {}> = {},
-) => {
-    const { invoke, subscribe, unsubscribe, isConnected } = useContext(EventEmitterContext);
-    const subscriptions = useRef<number[]>([]);
-    const isMounted = useRef(true);
-
-    useEffect(() => {
-        isMounted.current = true;
-
-        const registerAndSubscribe = async () => {
-            for (const [key, symbolName] of Object.entries(symbols)) {
-                try {
-                    const invokeOptions = options[key] ? { symbol_name: symbolName, options: options[key] } : { symbol_name: symbolName };
-                    await invoke("ADS.register_symbol", MessageType.Request, invokeOptions);
-
-                    //console.log(`Subscribe... ADS/${symbolName}`);
-                    const subscriptionId = subscribe(`ADS/${symbolName}`, (data) => {
-                        if (isMounted.current) {
-                            const setter = setters[key];
-                            if (setter) {
-                                setter(data.value);
-                            }
-                        }
-                    });
-                    subscriptions.current.push(subscriptionId);
-                } catch (err) {
-                    console.error(`Failed to register symbol ${symbolName}: ${err}`);
-                }
-            }
-            await invoke("ADS.refresh", MessageType.Request, {});
-        };
-        
-        if (!isConnected() ) {
-            //console.log("SCHEDULE LATER...");
-            let connectionSubId = subscribe("HUB/connected", () => {
-                registerAndSubscribe();
-                unsubscribe(connectionSubId);
-            });
-            subscriptions.current.push(connectionSubId);
-        }
-        else {
-            //console.log("ALREADY CONNECTED...");
-            registerAndSubscribe();
-        }
-        
-
-        return () => {
-            //console.log("UNSUBSCRIBE");
-            isMounted.current = false;
-            subscriptions.current.forEach(subscriptionId => unsubscribe(subscriptionId));
-            subscriptions.current = [];
-        };
-    }, []); // Ensure setters and symbols are included if they can change
-
-    return null; // This hook does not render anything
-};
-
-
-/**
- * Custom hook to create a function that sends a specified value to a remote device or server.
- * This hook abstracts the repetitive logic involved in sending these values,
- * such as invoking the command and handling errors.
- *
- * @param {string} domain The domain under which the backend function is grouped.
- * @param {string} fname The name of the function to be called on the backend.
- * @param {string} symbolName The symbol name that identifies the specific value or setting in the backend.
- * @returns {Function} A function that accepts a value (number or boolean) and sends it to the configured backend.
- *
- * @example
- * ```tsx
- * import React, { useState } from 'react';
- * import { Button } from 'primereact/button';
- * import useWriteValue from './useWriteValue'; // adjust the import path as necessary
- *
- * const Component: React.FC = () => {
- *   const [value, setValue] = useState<number>(0);
- *   const writeToBackend = useAdsWriteValue("ADS", "write_value", "GNV.mySymbol");
- *
- *   return (
- *     <div>
- *       <input
- *         type="number"
- *         value={value}
- *         onChange={(e) => setValue(Number(e.target.value))}
- *       />
- *       <Button
- *         label="Send to Backend"
- *         onClick={() => writeToBackend(value)}
- *       />
- *     </div>
- *   );
- * };
- */
-export function useAdsWriteValue(symbolName: string) {
-    const { write } = useContext(EventEmitterContext);
-
-    // Return a function that takes a value and sends it to the backend
-    return async (value: object | boolean | number | string) => {
-        try {
-            // Use FQDN topic: ADS.symbolName
-            await write(`ADS.${symbolName}`, value);
-        } catch (err) {
-            console.error(`Error writing tag ${symbolName}: ${err}`);
-        }
-    };
-}
-
-
-
-
-
-
-/**
- * useAdsWriteScaledValue is a custom React hook that enables writing scaled numerical values to a backend system.
- * It applies a specified scale and offset to a numeric value before sending it over an ADS connection.
- * This hook is ideal for scenarios where numeric data needs to be adjusted according to dynamically configurable
- * scale factors before being persisted or processed by a backend system.
- *
- * @param symbolName The symbol name in the backend system where the value will be written.
- * @param scale The scale factor to be applied to the value.
- * @param offset The offset to be applied after scaling the value.
- * @returns A function that takes a numeric value, applies the scaling and offset, and sends the modified value to the backend.
- *
- * @example
- * This example demonstrates how to use the `useAdsWriteScaledValue` hook within a component that allows users
- * to input a value in inches, which is then automatically converted to millimeters (if the scale is set for such conversion)
- * based on a dynamic scale factor managed in the component's state.
- *
- * ```tsx
- * import React, { useState } from 'react';
- * import { useAdsWriteScaledValue } from './hooks';
- *
- * const MeasurementInput: React.FC = () => {
- *     const [scale, setScale] = useState<number>(1 / 25.4); // Initial scale for converting inches to millimeters.
- *     const [offset, setOffset] = useState<number>(0); // No offset by default.
- *
- *     // The hook is used here with the scale and offset state variables.
- *     const writeMeasurement = useAdsWriteScaledValue("GIO.axisX.position", scale, offset);
- *
- *     // This function is called when the input field value changes.
- *     const handleMeasurementChange = (event: React.ChangeEvent<HTMLInputElement>) => {
- *         const valueInInches = parseFloat(event.target.value);
- *         writeMeasurement(valueInInches); // Write the scaled value (converted to millimeters).
- *     };
- *
- *     return (
- *         <div>
- *             <label>Enter measurement in inches:</label>
- *             <input type="number" onChange={handleMeasurementChange} />
- *         </div>
- *     );
- * };
- *
- * export default MeasurementInput;
- * ```
- *
- * In this component, `writeMeasurement` is a function returned by the `useAdsWriteScaledValue` hook that takes a value in inches,
- * converts it to millimeters using the current `scale`, and writes the result to a backend symbol. The `scale` and `offset` can be adjusted
- * dynamically if needed, for instance, based on user selection or other external configurations.
- */
-export function useAdsWriteScaledValue(symbolName: string, scale: number, offset: number) {
-    const { write } = useContext(EventEmitterContext);
-
-    return useCallback(async (value: number) => {
-
-        // In autocore-react, we multiply to scale incoming values,
-        // divide to scale outgoing values.
-        // This is an OUTGOING value, so we divide.
-
-        const scaledValue = (value - offset) / scale;
-        try {
-            // Use FQDN topic: ADS.symbolName
-            await write(`ADS.${symbolName}`, scaledValue);
-        } catch (err) {
-            console.error(`Error writing scaled value to tag ${symbolName}: ${err}`);
-        }
-    }, [symbolName, scale, offset, write]);
-}
-
-
-
-
-
-/**
- * Custom hook to send a "tap" action, which sends true followed by false after a short delay,
- * to a specified symbol in the backend. This is used to simulate a button tap or momentary switch.
- *
- * @param {string} domain - The domain under which the backend function is grouped.
- * @param {string} fname - The function name to be called on the backend.
- * @param {string} symbolName - The symbol name to target for the tap action.
- * @returns {Function} A function that triggers the tap action.
- *
- * @example
- * ```tsx
- * import React from 'react';
- * import { Button } from 'primereact/button';
- * import useTapValue from './useTapValue'; // Ensure the correct import path
- *
- * const MyComponent: React.FC = () => {
- *   const sendTapAction = useTapValue("ADS", "write_value", "GNV.myButton");
- *
- *   return (
- *     <Button
- *       label="Tap Button"
- *       onClick={() => sendTapAction()}
- *     />
- *   );
- * };
- * ```
- */
-export function useAdsTapValue(symbolName: string): () => Promise<void> {
-    const { write } = useContext(EventEmitterContext);
-
-    return async () => {
-        try {
-            // Use FQDN topic: ADS.symbolName
-            const topic = `ADS.${symbolName}`;
-            await write(topic, true);
-            await sleep(300); // Sleep for 300ms before writing false
-            await write(topic, false);
-        } catch (err) {
-            console.error(`Error handling tap action for ${symbolName}: ${err}`);
-        }
-    };
-}
-
+/*
+ * Copyright (C) 2024 Automated Design Corp.. All Rights Reserved.
+ * Created Date: 2024-04-26 09:04:40
+ * -----
+ * Last Modified: 2026-01-29 09:33:22
+ * -----
+ * 
+ */
+
+
+
+import { useContext, useRef, useEffect, useCallback } from 'react';
+import { EventEmitterContext } from '../core/EventEmitterContext';
+import { MessageType } from '../hub/CommandMessage';
+
+
+/**
+ * Sleep for a given number of milliseconds.
+ * @param ms Number of milliseconds to sleep.
+ */
+function sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+
+
+
+/**
+ * Custom hook for registering symbols and subscribing to updates on the 
+ * ADS domain via the EventEmitterContext.
+ * This hook abstracts the common pattern of registering symbols and handling subscriptions
+ * to updates in components that need real-time data from a backend service.
+ *
+ * @param setters A mapping of state setter functions, where each key corresponds to a piece of state
+ *                related to a symbol, and each value is the setter function for that state.
+ * @param symbols A mapping of state keys to their corresponding symbol names in the backend system.
+ *                Each key should match a key in the `setters` object, and each value should be a string
+ *                that represents the symbol name to register and subscribe to.
+ *
+ * ## Usage Example:
+ * ```typescript
+ * const setters = {
+ *     speed: setSpeed,
+ *     temperature: setTemperature
+ * };
+ *
+ * const symbols = {
+ *     speed: "Sensor.speed",
+ *     temperature: "Sensor.temperature"
+ * };
+ *
+ * useRegisterSymbols(setters, symbols);
+ * ```
+ *
+ * This will register and subscribe to updates for "Sensor.speed" and "Sensor.temperature",
+ * and update the `speed` and `temperature` states via `setSpeed` and `setTemperature` respectively
+ * whenever new data is received.
+ */
+export const useAdsRegisterSymbols = (
+    setters: Record<string, (value: any) => void>, 
+    symbols: Record<string, string>,
+    options: Record<string, {}> = {},
+) => {
+    const { invoke, subscribe, unsubscribe, isConnected } = useContext(EventEmitterContext);
+    const subscriptions = useRef<number[]>([]);
+    const isMounted = useRef(true);
+
+    useEffect(() => {
+        isMounted.current = true;
+
+        const registerAndSubscribe = async () => {
+            for (const [key, symbolName] of Object.entries(symbols)) {
+                try {
+                    const invokeOptions = options[key] ? { symbol_name: symbolName, options: options[key] } : { symbol_name: symbolName };
+                    await invoke("ADS.register_symbol", MessageType.Request, invokeOptions);
+
+                    //console.log(`Subscribe... ADS/${symbolName}`);
+                    const subscriptionId = subscribe(`ADS/${symbolName}`, (data) => {
+                        if (isMounted.current) {
+                            const setter = setters[key];
+                            if (setter) {
+                                setter(data.value);
+                            }
+                        }
+                    });
+                    subscriptions.current.push(subscriptionId);
+                } catch (err) {
+                    console.error(`Failed to register symbol ${symbolName}: ${err}`);
+                }
+            }
+            await invoke("ADS.refresh", MessageType.Request, {});
+        };
+        
+        if (!isConnected() ) {
+            //console.log("SCHEDULE LATER...");
+            let connectionSubId = subscribe("HUB/connected", () => {
+                registerAndSubscribe();
+                unsubscribe(connectionSubId);
+            });
+            subscriptions.current.push(connectionSubId);
+        }
+        else {
+            //console.log("ALREADY CONNECTED...");
+            registerAndSubscribe();
+        }
+        
+
+        return () => {
+            //console.log("UNSUBSCRIBE");
+            isMounted.current = false;
+            subscriptions.current.forEach(subscriptionId => unsubscribe(subscriptionId));
+            subscriptions.current = [];
+        };
+    }, []); // Ensure setters and symbols are included if they can change
+
+    return null; // This hook does not render anything
+};
+
+
+/**
+ * Custom hook to create a function that sends a specified value to a remote device or server.
+ * This hook abstracts the repetitive logic involved in sending these values,
+ * such as invoking the command and handling errors.
+ *
+ * @param {string} domain The domain under which the backend function is grouped.
+ * @param {string} fname The name of the function to be called on the backend.
+ * @param {string} symbolName The symbol name that identifies the specific value or setting in the backend.
+ * @returns {Function} A function that accepts a value (number or boolean) and sends it to the configured backend.
+ *
+ * @example
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { Button } from 'primereact/button';
+ * import useWriteValue from './useWriteValue'; // adjust the import path as necessary
+ *
+ * const Component: React.FC = () => {
+ *   const [value, setValue] = useState<number>(0);
+ *   const writeToBackend = useAdsWriteValue("ADS", "write_value", "GNV.mySymbol");
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         type="number"
+ *         value={value}
+ *         onChange={(e) => setValue(Number(e.target.value))}
+ *       />
+ *       <Button
+ *         label="Send to Backend"
+ *         onClick={() => writeToBackend(value)}
+ *       />
+ *     </div>
+ *   );
+ * };
+ */
+export function useAdsWriteValue(symbolName: string) {
+    const { write } = useContext(EventEmitterContext);
+
+    // Return a function that takes a value and sends it to the backend
+    return async (value: object | boolean | number | string) => {
+        try {
+            // Use FQDN topic: ADS.symbolName
+            await write(`ADS.${symbolName}`, value);
+        } catch (err) {
+            console.error(`Error writing tag ${symbolName}: ${err}`);
+        }
+    };
+}
+
+
+
+
+
+
+/**
+ * useAdsWriteScaledValue is a custom React hook that enables writing scaled numerical values to a backend system.
+ * It applies a specified scale and offset to a numeric value before sending it over an ADS connection.
+ * This hook is ideal for scenarios where numeric data needs to be adjusted according to dynamically configurable
+ * scale factors before being persisted or processed by a backend system.
+ *
+ * @param symbolName The symbol name in the backend system where the value will be written.
+ * @param scale The scale factor to be applied to the value.
+ * @param offset The offset to be applied after scaling the value.
+ * @returns A function that takes a numeric value, applies the scaling and offset, and sends the modified value to the backend.
+ *
+ * @example
+ * This example demonstrates how to use the `useAdsWriteScaledValue` hook within a component that allows users
+ * to input a value in inches, which is then automatically converted to millimeters (if the scale is set for such conversion)
+ * based on a dynamic scale factor managed in the component's state.
+ *
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { useAdsWriteScaledValue } from './hooks';
+ *
+ * const MeasurementInput: React.FC = () => {
+ *     const [scale, setScale] = useState<number>(1 / 25.4); // Initial scale for converting inches to millimeters.
+ *     const [offset, setOffset] = useState<number>(0); // No offset by default.
+ *
+ *     // The hook is used here with the scale and offset state variables.
+ *     const writeMeasurement = useAdsWriteScaledValue("GIO.axisX.position", scale, offset);
+ *
+ *     // This function is called when the input field value changes.
+ *     const handleMeasurementChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+ *         const valueInInches = parseFloat(event.target.value);
+ *         writeMeasurement(valueInInches); // Write the scaled value (converted to millimeters).
+ *     };
+ *
+ *     return (
+ *         <div>
+ *             <label>Enter measurement in inches:</label>
+ *             <input type="number" onChange={handleMeasurementChange} />
+ *         </div>
+ *     );
+ * };
+ *
+ * export default MeasurementInput;
+ * ```
+ *
+ * In this component, `writeMeasurement` is a function returned by the `useAdsWriteScaledValue` hook that takes a value in inches,
+ * converts it to millimeters using the current `scale`, and writes the result to a backend symbol. The `scale` and `offset` can be adjusted
+ * dynamically if needed, for instance, based on user selection or other external configurations.
+ */
+export function useAdsWriteScaledValue(symbolName: string, scale: number, offset: number) {
+    const { write } = useContext(EventEmitterContext);
+
+    return useCallback(async (value: number) => {
+
+        // In autocore-react, we multiply to scale incoming values,
+        // divide to scale outgoing values.
+        // This is an OUTGOING value, so we divide.
+
+        const scaledValue = (value - offset) / scale;
+        try {
+            // Use FQDN topic: ADS.symbolName
+            await write(`ADS.${symbolName}`, scaledValue);
+        } catch (err) {
+            console.error(`Error writing scaled value to tag ${symbolName}: ${err}`);
+        }
+    }, [symbolName, scale, offset, write]);
+}
+
+
+
+
+
+/**
+ * Custom hook to send a "tap" action, which sends true followed by false after a short delay,
+ * to a specified symbol in the backend. This is used to simulate a button tap or momentary switch.
+ *
+ * @param {string} domain - The domain under which the backend function is grouped.
+ * @param {string} fname - The function name to be called on the backend.
+ * @param {string} symbolName - The symbol name to target for the tap action.
+ * @returns {Function} A function that triggers the tap action.
+ *
+ * @example
+ * ```tsx
+ * import React from 'react';
+ * import { Button } from 'primereact/button';
+ * import useTapValue from './useTapValue'; // Ensure the correct import path
+ *
+ * const MyComponent: React.FC = () => {
+ *   const sendTapAction = useTapValue("ADS", "write_value", "GNV.myButton");
+ *
+ *   return (
+ *     <Button
+ *       label="Tap Button"
+ *       onClick={() => sendTapAction()}
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export function useAdsTapValue(symbolName: string): () => Promise<void> {
+    const { write } = useContext(EventEmitterContext);
+
+    return async () => {
+        try {
+            // Use FQDN topic: ADS.symbolName
+            const topic = `ADS.${symbolName}`;
+            await write(topic, true);
+            await sleep(300); // Sleep for 300ms before writing false
+            await write(topic, false);
+        } catch (err) {
+            console.error(`Error handling tap action for ${symbolName}: ${err}`);
+        }
+    };
+}
+