@pepperdash/mobile-control-react-app-core 1.24.0-feat-essentials-v3.4 → 1.24.0

package/README.md

@@ -1,39 +1,109 @@
 # Mobile Control React App Core Library
 
-This library uses vite for React.
+This library provides the necessary building blocks for developing React apps for [PepperDash Mobile Control](https://github.com/PepperDash/epi-essentials-mobile-control) systems. It is built with Vite and includes:
 
-The purpose of this library is to provide the necessary building blocks to make developing React apps for Mobile Control easier and more efficient.
-
-Primarily, it provides a series of React hooks that handle API interaction with corresponding messengers in the [Essentials Mobile Control Plugin](https://github.com/PepperDash/epi-essentials-mobile-control) (or other Essentials plugins) as well as typescript interfaces for the device state objects that each messenger uses.
-
-In addition, it also provides some core React components that can be consumed by a React App and deal with the particulars of running an HTML5 app on a touch device and allow interaction between button events to achieve press/hold/release functionality commonly necessary for things like ramping volume controls or sending IR commands.
-
-At the core of this library is a React Context that is intended to generate a websocket client that handles all the messaging to and from the Mobile Control Plugin.  Along with that context, Redux is used to handle maintining the state for the room and all devices relevant to the current session.  Redux selectors are provided for accessing common data in the store by room or device.
+- **React hooks** — Handle API interaction with corresponding messengers in the Essentials Mobile Control Plugin (or other Essentials plugins)
+- **TypeScript interfaces** — Typed device state objects for each messenger
+- **Core React components** — Handle touch device interaction, including press/hold/release functionality needed for things like volume ramping and IR commands
+- **WebSocket context** — Generates and manages a WebSocket client for all messaging between the app and the Mobile Control Plugin
+- **Redux store** — Maintains room and device state for the current session, with selectors for accessing data by room or device
 
 ## How Mobile Control Works
 
-Mobile control uses a websocket to allow JSON formatted messages to be passed between the client app, running in React, and the Essentials Control System application.
-
-When the client initially connects to the control system, it makes an HTTP call to join a particular room.  The response to that call provides the React app with the necessary information to connect to the websocket server. The server can either be running directly on the Crestron control system processor or it can also be running on the Mobile Control Edge Server, which then acts as a message relay to the control system.
-
-Once a websocket connection is established, the React app must then request the room state and configuration which it will subsequently use to determine which device states it needs to request from the control system.
-
-Supplied in this library is a hook (useGetAllDeviceStateFromRoomConfiguration) that takes a RoomConfiguration object and will then iterate the devices for that room and request their current full status.  This hook should be called at the root level of the React App.
+Mobile Control uses a WebSocket to pass JSON messages between a React client and the Essentials control system application. The connection flow is:
 
-From that point forward, room and device state messages from the control system will be partial objects and will get overlayed onto the room/device state object in the store.
+1. The client makes an HTTP call to join a room on the control system
+2. The response provides the information needed to open a WebSocket connection
+3. The WebSocket server can run directly on the Crestron processor or on the Mobile Control Edge Server (which relays messages to the processor)
+4. Once connected, the app requests the room state and configuration
+5. The app uses that configuration to determine which device states to request — the `useGetAllDeviceStateFromRoomConfiguration` hook handles this automatically and should be called at the root level of your app
+6. From that point on, room and device state updates arrive as partial objects and are merged into the Redux store
 
 ## 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.
+Use the provided hooks to link buttons and UI elements to the Mobile Control API without managing the communication layer directly:
 
-# How to Set up Your Development Environment
-
-Run `npm install` to install the required dependencies.
-
-Load an instance of an Essentials v2.x program as well as the Essentials Mobile Control plugin v4.x to a Crestron program slot.  Consult the Mobile Control plugin for direct server plugin configuration instructions.
+- **Core hooks** (provided here) — Cover the standard messengers in the Mobile Control Plugin and handle the common needs of most systems
+- **Custom hooks** (written in your app) — Can integrate directly with any messenger defined in an Essentials room or device plugin, enabling extensibility for application-specific or esoteric needs without requiring changes to this library
 
-Copy the `/public/_local-config/_config.default.json` to a file called `/public/_local-config/_config.local.json` and modify the `apiPath` value to point to the IP address of your test processor as well as the correct port.  This file should *not* be added to the git repository because it applies only to your local test environment.
-
-Run the app with `npm run dev` which will start the development server.  The vite development server will then print it's local URL (eg: http://localhost:5173/mc/app).  Open this URL in a browser.  Initially you will just get a message saying that the client is disconnected.  You will need to supply a token in the url as a search param that will associate your client with a particular client instance on the Mobile Control server.  To get a token, run the `mobileinfo:[programSlot]` console command on the Crestron processor and copy the token value associated with the client instance you want your development client to connect to and paste it into the url as the token value (eg: http://localhost:5173/mc/app?token=[some-token-value]).
+# How to Set up Your Development Environment
 
-Your development client instance should now connect to the websocket server running on the Crestron program.
+### Prerequisites
+
+- Essentials v2.x program loaded to a Crestron program slot
+- Essentials Mobile Control Plugin v4.x configured in that program (consult the plugin docs for server configuration)
+
+### Steps
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Create a local config file by copying the default:
+   ```
+   /public/_local-config/_config.default.json  →  /public/_local-config/_config.local.json
+   ```
+   Update the `apiPath` value to the IP address and port of your test processor. **Do not commit this file** — it is gitignored.
+
+   Example `_config.local.json`:
+   ```json
+   {
+     "apiPath": "http://192.168.1.22:50010/mc/api",
+     "gatewayAppPath": "",
+     "enableDev": false,
+     "logoPath": "logo/PDT-logo-no-tag_blue-pdt-on-transp_1000px.png",
+     "loginMode": "room-list",
+     "iconSet": "GOOGLE",
+     "modes": {
+       "room-list": {
+         "listPageText": "Please select your room",
+         "loginHelpText": "Please select your room from the list, then enter the code shown on the display in the room. (Configurable message)",
+         "passcodePageText": "Please enter the code shown on this room's display"
+       }
+     }
+   }
+   ```
+
+3. Start the development server:
+   ```bash
+   npm run dev
+   ```
+
+4. Open the printed local URL in a browser (e.g. `http://localhost:5173/mc/app`). You will see a disconnected message until a token is provided.
+
+5. Get a connection token from the Crestron processor by running the console command:
+   ```
+   mobileinfo:[programSlot]
+   ```
+   Example output:
+   ```
+    mobileadduiclient:1 room1 1234567890abcdefghijk
+    mobileinfo
+
+    Mobile Control Edge Server API Information:
+        Not Enabled in Config.
+
+    Mobile Control Direct Server Infromation:
+        User App URL: http://10.11.50.177:50001/mc/app?token=[insert_client_token]
+        Server port: 50001
+
+        UI Client Info:
+        Tokens Defined: 1
+        Clients Connected: 0
+
+    Client 1:
+    Room Key: room1
+    Token: f0f19b7e-606a-4f91-875e-7847e28bc709
+    Client URL: http://10.11.50.177:50001/mc/app?token=f0f19b7e-606a-4f91-875e-7847e28bc709
+    Connected: False
+    Duration: Not Connected
+   ```
+   Copy the token value for the client instance you want to connect to.
+
+6. Append the token to the URL and reload:
+   ```
+   http://localhost:5173/mc/app?token=[your-token-value]
+   ```
+
+Your development client will now connect to the WebSocket server running on the Crestron program.