docs: Updates readme and adds jdoc comments for all interface hooks

README.md

@@ -24,3 +24,4 @@ From that point forward, room and device state messages from the control system
 
 ## How this Library is Intended to be Used
 
+The intent is to use the various hooks provided in this library to easily link up to buttons and other elements on an HTML5 UI in a React App to handle the heavy lifting of integrating with the Mobile Control API.  This library will provide hooks for the messengers in the Mobile Control plugin, but you will also be able to write hooks in the React App for custom API that can integrate directly with a messenger defined in any Essentials room or device plugin.  This allows consistency with the core communication that most systems will rely on, while also providing easy customization and extensibility for more esoteric or application specific needs that may not see wide use and justify inclusion in this library.

src/lib/shared/hooks/interfaces/index.ts

@@ -2,7 +2,7 @@ export * from "./interfaceNames";
 export * from "./useAvrControl";
 export * from "./useEndpoint";
 export * from "./useIBasicVolumeWithFeedback";
-export * from "./useIChannelMessenger";
+export * from "./useIChannel";
 export * from "./useIColor";
 export * from "./useICommunicationMonitor";
 export * from "./useIDPad";
@@ -19,15 +19,16 @@ export * from "./useIMcCiscoCodecUserInterfaceAppControl";
 export * from "./useINumeric";
 export * from "./useIProjectorScreenLiftControl";
 export * from "./useIRoomEventSchedule";
+export * from "./useIRunDefaultPresentRoute";
 export * from "./useIRunDirectRouteAction";
 export * from "./useIRunRouteAction";
 export * from "./useISetTopBoxcontrols";
 export * from "./useIShadesOpenCloseStop";
 export * from "./useIShutdownPromptTimer";
 export * from "./useISwitchedOutput";
 export * from "./useITechPassword";
+export * from "./useITheme";
 export * from "./useITransport";
 export * from "./useMobileControlTouchpanelController";
 export * from "./useTwoWayDisplayBase";
-export * from "./useIRunDefaultPresentRoute";
-export * from "./useITheme";
+

src/lib/shared/hooks/interfaces/useAvrControl.ts

@@ -8,6 +8,12 @@ import { IHasPowerWithFeedbackProps, useIHasPowerControl } from './useIHasPowerC
 import { IHasSelectableItemsReturn, useIHasSelectableItems } from './useIHasSelectableItems';
 import { IHasSurroundChannelsReturn, useIHasSurroundChannels } from './useIHasSurroundChannels';
 
+
+/**
+ * Provides a set of hooks to control an AVR device
+ * @param key key of the device
+ * @returns 
+ */
 export function useAvrControl(key: string): AvrReturn | undefined {
     const avrState = useGetDevice<PowerState>(key);
     const powerControl = useIHasPowerControl(key);

src/lib/shared/hooks/interfaces/useCameraBase.ts

@@ -1,7 +1,10 @@
 import { CameraState, PressHoldReleaseReturn, useGetDevice, useWebsocketContext } from 'src/lib';
 import { useButtonHeldHeartbeat } from '../useHeldButtonAction';
 
-
+/**
+ * Provides a set of hooks to control a device that extends the CameraBase class
+ * @param key key of the device
+ */
 export function useCameraBase(key: string): CameraBaseProps | undefined{
   const { sendMessage } = useWebsocketContext();
   const path = `/device/${key}`;

src/lib/shared/hooks/interfaces/useEndpoint.ts

@@ -1,7 +1,11 @@
 import { useGetDevice } from 'src/lib';
 import { EndpointState } from 'src/lib/types/state/state/endpointState/endpointState';
 
-
+/**
+ * A hook that provides access to the endpoint state
+ * @param key the key of the endpoint
+ * @returns 
+ */
 export function useEndpoint(key: string): IEndpointReturn | undefined {
 
     const endpointState = useGetDevice<EndpointState>(key);

src/lib/shared/hooks/interfaces/useIBasicVolumeWithFeedback.ts

@@ -3,6 +3,12 @@ import { useWebsocketContext } from "src/lib/utils/useWebsocketContext";
 import { useButtonHeldHeartbeat } from "../useHeldButtonAction";
 import { PressHoldReleaseReturn } from "../usePressHoldRelease";
 
+/**
+ * hook to control a volume device that implements the IBasicVolumeWithFeedback interface
+ * @param path path prefix to for the device. i.e. /device/{key} or /room/{key}
+ * @param volumeState 
+ * @returns 
+ */
 export function useIBasicVolumeWithFeedback(
   path: string, volumeState: Volume | undefined
 ): IBasicVolumeWithFeedbackReturn | undefined {
@@ -43,6 +49,7 @@ export interface IBasicVolumeWithFeedbackReturn {
   muteOff: () => void;
 }
 
+
 export function useGetIBasicVolumeWithFeedback(
   path: string, volumeState: Volume | undefined
 ): IBasicVolumeWithFeedbackReturn | undefined {

src/lib/shared/hooks/interfaces/useIChannelMessenger.ts → src/lib/shared/hooks/interfaces/useIChannel.ts

@@ -1,6 +1,11 @@
 import { useButtonHeldHeartbeat } from '../useHeldButtonAction';
 import { PressHoldReleaseReturn } from '../usePressHoldRelease';
 
+/**
+ * hook to control a channel messenger device that implements the IChannelMessenger interface
+ * @param key the key of the device
+ * @returns 
+ */
 export function useIChannelMessenger(key: string): IChannelMessengerProps | undefined {
 
     const path = `/device/${key}`;

src/lib/shared/hooks/interfaces/useIColor.ts

@@ -1,6 +1,11 @@
 import { useButtonHeldHeartbeat } from '../useHeldButtonAction';
 import { PressHoldReleaseReturn } from '../usePressHoldRelease';
 
+/**
+ * hook to control a device that implements the IColor interface
+ * @param key 
+ * @returns 
+ */
 export function useIColor(key: string): IColorProps | undefined {
   const path = `/device/${key}`;
 

src/lib/shared/hooks/interfaces/useICommunicationMonitor.ts

@@ -1,5 +1,11 @@
 import { CommunicationMonitorState, useGetDevice } from 'src/lib';
 
+
+/**
+ * hook to control a device that implements the ICommunicationMonitor interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useICommunicationMonitor(key: string): ICommunicationMonitorReturn | undefined {
   const device = useGetDevice<CommunicationMonitorState>(key);
 

src/lib/shared/hooks/interfaces/useIDPad.ts

@@ -1,6 +1,11 @@
 import { useButtonHeldHeartbeat } from "../useHeldButtonAction";
 import { PressHoldReleaseReturn } from "../usePressHoldRelease";
 
+/**
+ * hook to control a device that implements the IDPad interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useIDPad(key: string): IDPadProps | undefined {
   const path = `/device/${key}`;
 

src/lib/shared/hooks/interfaces/useIDeviceInfoMessenger.ts

@@ -1,6 +1,10 @@
 import { DeviceInfo, DeviceInfoState, useGetDevice } from 'src/lib';
 
-
+/**
+ * hook that returns the info for a device that implements the IDeviceInfo interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useIDeviceInfoMessenger(key: string): DeviceInfo | undefined {
   const device = useGetDevice<DeviceInfoState>(key);
 

src/lib/shared/hooks/interfaces/useIDspPresets.ts

@@ -1,5 +1,10 @@
 import { IKeyName, useWebsocketContext } from 'src/lib';
 
+/**
+ * hook to control a device that implements the IDspPresets interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useIDspPresets(key: string) {
     const { sendMessage } = useWebsocketContext();
 

src/lib/shared/hooks/interfaces/useIDvr.ts

@@ -1,6 +1,11 @@
 import { useButtonHeldHeartbeat } from '../useHeldButtonAction';
 import { PressHoldReleaseReturn } from '../usePressHoldRelease';
 
+/**
+ * hook to control a device that implements the IDvr interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useIDvr(key: string): IDvrProps | undefined {
   const path = `/device/${key}`;
 

src/lib/shared/hooks/interfaces/useIEssentialsRoomCombiner.ts

@@ -2,6 +2,11 @@ import { useGetDevice } from 'src/lib/store';
 import { IEssentialsRoomCombinerState } from 'src/lib/types/state/state/IEssentialsRoomCombinerState';
 import { useWebsocketContext } from 'src/lib/utils';
 
+/**
+ * hook to control a device that implements the IEssentialsRoomCombiner interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useIEssentialsRoomCombiner(key: string): IEssentialsRoomCombinerReturn | undefined {
   const { sendMessage } = useWebsocketContext();
   const roomCombinerState = useGetDevice(key) as IEssentialsRoomCombinerState | undefined;

src/lib/shared/hooks/interfaces/useIHasPowerControl.ts

@@ -1,5 +1,10 @@
 import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext';
 
+/**
+ * hook to control a device that implements the IHasPowerControl interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useIHasPowerControl(key: string): IHasPowerWithFeedbackProps {
   const { sendMessage } = useWebsocketContext();
 

src/lib/shared/hooks/interfaces/useIHasSelectableItems.ts

@@ -1,9 +1,12 @@
 import { useGetDevice } from 'src/lib/store';
 import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext';
 
+
 /**
  * Hook for devices that have selectable items
  * TState is the type of the expected state of the device
+ * @param key key of the device
+ * @returns 
  */
 export function useIHasSelectableItems<TState>(key: string): IHasSelectableItemsReturn<TState> | undefined {
   const { sendMessage } = useWebsocketContext();

src/lib/shared/hooks/interfaces/useIHasSurroundChannels.ts

@@ -1,7 +1,11 @@
 import { LevelControlsState, Volume, useGetDevice } from 'src/lib';
 import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext';
 
-
+/**
+ * hook to control a device that implements the IHasSurroundChannels interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useIHasSurroundChannels(key: string): IHasSurroundChannelsReturn | undefined {
   const { sendMessage } = useWebsocketContext();
 

src/lib/shared/hooks/interfaces/useILevelControls.ts

@@ -2,7 +2,11 @@ import { useGetDevice, useRoomLevelControls } from 'src/lib/store';
 import { LevelControlsState } from 'src/lib/types/state/state/LevelControlsState';
 import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext';
 
-
+/**
+ * hook that controls a device that implements the ILevelControls interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useILevelControls(key: string): ILevelControlsReturn | undefined {
   const { sendMessage, sendSimpleMessage } = useWebsocketContext();
   const device = useGetDevice<LevelControlsState>(key);

src/lib/shared/hooks/interfaces/useILightingScenes.ts

@@ -2,6 +2,11 @@ import { useGetDevice } from 'src/lib/store';
 import { LightingScene, LightingState } from 'src/lib/types';
 import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext';
 
+/**
+ * hook to control a device that implements the ILightingScenes interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useILightingScenes(key: string): ILightingScenesReturn | undefined {
   const { sendMessage } = useWebsocketContext();
   const state = useGetDevice<LightingState>(key);

src/lib/shared/hooks/interfaces/useIMcCiscoCodecUserInterfaceAppControl.ts

@@ -1,5 +1,10 @@
 import { useWebsocketContext } from 'src/lib/utils';
 
+/**
+ * hook to control a device that implements the IMcCiscoCodecUserInterfaceAppControl interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useIMcCiscoCodecUserInterfaceAppControl(key: string) {
     const { sendMessage } = useWebsocketContext();
 

src/lib/shared/hooks/interfaces/useINumeric.ts

@@ -2,7 +2,7 @@ import { useButtonHeldHeartbeat } from '../useHeldButtonAction';
 import { PressHoldReleaseReturn } from '../usePressHoldRelease';
 
 /**
- * hook to return the functions to trigger for a numeric keypad
+ * hook to return the functions to trigger for a numeric keypad for a device that implements the INumeric interface
  * @param key device key
  * @returns 
  */

src/lib/shared/hooks/interfaces/useIProjectorScreenLiftControl.ts

@@ -1,6 +1,10 @@
 import { IProjectorScreenLiftControlState, useGetDevice, useWebsocketContext } from 'src/lib';
 
-
+/**
+ * hook to control a device that implements the IProjectorScreenLiftControl interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useIProjectorScreenLiftControl(key: string): IProjectorScreenLiftControlReturn | undefined {
     const { sendMessage } = useWebsocketContext();
     const projectorScreenLiftControlState = useGetDevice(key) as IProjectorScreenLiftControlState | undefined;

src/lib/shared/hooks/interfaces/useIRoomEventSchedule.ts

@@ -1,6 +1,12 @@
 import { ScheduleEvent, ScheduleState, useRoomState } from 'src/lib';
 import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext';
 
+
+/**
+ * hook to control a device that implements the IRoomEventSchedule interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useIRoomEventSchedule(key: string): IRoomEventScheduleReturn | undefined {
     const { sendMessage } = useWebsocketContext();
     const roomEventScheduleState = useRoomState(key) as ScheduleState | undefined;

src/lib/shared/hooks/interfaces/useIRunDefaultPresentRoute.ts

@@ -1,10 +1,15 @@
 import { useWebsocketContext } from "src/lib/utils";
 
-export function useIRunDefaultPresentRoute(key: string):IRunDefaultPresentRouteProps {
+/**
+ * hook to control a room that implements the IRunDefaultPresentRoute interface
+ * @param roomKey key of the room
+ * @returns 
+ */
+export function useIRunDefaultPresentRoute(roomKey: string):IRunDefaultPresentRouteProps {
   const { sendMessage } = useWebsocketContext();
 
   const runDefaultPresentRoute = () => {
-    sendMessage(`/room/${key}/defaultsource`, {});
+    sendMessage(`/room/${roomKey}/defaultsource`, {});
   };
 
   return {runDefaultPresentRoute}

src/lib/shared/hooks/interfaces/useIRunDirectRouteAction.ts

@@ -1,5 +1,10 @@
 import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext';
 
+/**
+ * 
+ * @param roomKey key of the room
+ * @returns 
+ */
 export function useIRunDirectRouteAction(roomKey: string): IRunDirectRouteActionProps {
     const { sendMessage } = useWebsocketContext();
 

src/lib/shared/hooks/interfaces/useIRunRouteAction.ts

@@ -2,12 +2,17 @@ import { useGetDevice } from 'src/lib/store';
 import { RoutingState } from 'src/lib/types';
 import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext';
 
-export function useIRunRouteAction(key: string): IRunRouteActionProps | undefined {
+/**
+ * hook to control a room that implements the IRunRouteAction interface
+ * @param roomKey key of the room
+ * @returns 
+ */
+export function useIRunRouteAction(roomKey: string): IRunRouteActionProps | undefined {
   const { sendMessage } = useWebsocketContext();
-  const routingState = useGetDevice<RoutingState>(key);
+  const routingState = useGetDevice<RoutingState>(roomKey);
 
   const runRoute = (request: RouteRequest) => {
-    sendMessage(`/room/${key}/source`, request);
+    sendMessage(`/room/${roomKey}/source`, request);
   };
 
   return { routingState, runRoute };

src/lib/shared/hooks/interfaces/useISetTopBoxcontrols.ts

@@ -1,6 +1,11 @@
 import { useButtonHeldHeartbeat } from '../useHeldButtonAction';
 import { PressHoldReleaseReturn } from '../usePressHoldRelease';
 
+/**
+ * hook to control a device that implements the ISetTopBoxControls interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useISetTopBoxControls(key: string): ISetTopBoxControlsProps {
   const path = `/device/${key}`;
 

src/lib/shared/hooks/interfaces/useIShadesOpenCloseStop.ts

@@ -2,7 +2,11 @@ import { useGetDevice } from 'src/lib/store';
 import { ShadeState } from 'src/lib/types';
 import { useWebsocketContext } from 'src/lib/utils/useWebsocketContext';
 
-
+/**
+ * hook that controls a device that implements the IShadesOpenCloseStop interface
+ * @param key key of the device
+ * @returns 
+ */
 export function useIShadesOpenCloseStop(key: string): IShadesOpenCloseStopProps | undefined {
   const { sendMessage } = useWebsocketContext();
   const shadeState = useGetDevice<ShadeState>(key);