feat(PE-1039): Add examples to enable ldws on a player

examples/enable-ldws-example/README.md

@@ -0,0 +1,147 @@
+# Enable Local Diagnostic Web Server (LDWS) Example
+
+## Introduction
+
+This example demonstrates three different methods to enable and configure the Local Diagnostic Web Server (LDWS) on a BrightSign device. The LDWS provides a web interface for device diagnostics, monitoring, and configuration that can be accessed from a web browser on the same network.
+
+## Overview and Directory Structure
+
+- **BrightScript Method** (recommended for most applications):
+  - `autorun.brs` — BrightScript application at the root of this directory. Enables LDWS using `roNetworkConfiguration`.
+
+- **Node.js Method** (recommended for Node.js-based projects):
+  - `javascript/autorun.brs` — BrightScript autorun file to launch the Node.js example.
+  - `javascript/index.js` — Node.js application that enables LDWS using the `@brightsign/dwsconfiguration` module.
+
+- **Registry Method** (lowest priority, not recommended unless required):
+  - `registry-config/autorun.brs` — BrightScript application that enables LDWS by writing directly to the registry.
+
+## Method 1: BrightScript with roNetworkConfiguration (**Recommended**)
+
+**File:** `autorun.brs` (in this directory)
+
+This method uses the `roNetworkConfiguration` object's `SetupDWS()` function to configure the LDWS settings.
+
+**How it works & Features:**
+- Uses the BrightScript `roNetworkConfiguration` API to enable LDWS with a custom password
+- Applies configuration immediately and reboots only if required
+- Automatically retrieves and displays the device's IP address in the console output (see [BrightSign Shell documentation](https://docs.brightsign.biz/developers/brightsign-shell) for console access)
+
+### Configuration Options:
+- `open`: Sets the password for LDWS access
+- `port`: Sets the HTTP port for the web server (default: 80)
+- The function returns `true` if a reboot is required to apply changes
+
+## Method 2: Node.js with @brightsign/dwsconfiguration Module
+
+**Files:** `javascript/autorun.brs` and `javascript/index.js`
+
+This method uses the Node.js `@brightsign/dwsconfiguration` module to configure LDWS settings. The BrightScript `autorun.brs` in the `javascript/` folder launches the Node.js script.
+
+**How it works:**
+- Uses the Node.js `@brightsign/dwsconfiguration` module to enable LDWS with flexible configuration options
+- Supports multiple authentication methods and password obfuscation
+- Checks if LDWS is already enabled before applying configuration
+- Only reboots if configuration changes are needed
+
+### Configuration Options:
+- `port`: HTTP port for the web server (default: 80)
+- `password.value`: Password for accessing the web interface
+- `password.obfuscated`: Whether the password is obfuscated (false = plain text)
+- `authenticationList`: Array of supported authentication methods (e.g., ["digest"])
+
+## Method 3: Registry Settings (**Not recommended unless required**)
+
+**File:** `registry-config/autorun.brs`
+
+This method uses the BrightSign registry to configure LDWS settings. It is the least preferred method and should only be used if the other two are not possible.
+
+**How it works:**
+- Uses direct registry manipulation to enable LDWS
+- Checks if LDWS is already enabled to prevent redundant configuration
+- Reboots the device to apply registry changes
+- No password protection (less secure than other methods)
+
+### Configuration Options:
+These registry keys work independently and can be used separately:
+- `http_server`: Sets the port number for the HTTP server (enables LDWS on specified port)
+- `dwse`: Enables the local DWS when disabled from setup package (only needed if previously disabled by setup)
+
+## Running the Examples
+
+**Note**: Check the console output for additional information regarding accessing the web interface with your configured password. (See [BrightSign Shell documentation](https://docs.brightsign.biz/developers/brightsign-shell) for console access)
+
+### Method 1 (BrightScript - Recommended)
+1. Copy `autorun.brs` (from this directory) to the root of your SD card.
+2. Insert the SD card into your BrightSign player and power on (or restart if already running).
+3. The device will automatically configure LDWS and reboot if necessary.
+4. Check the console output for the actual device IP address
+
+### Method 2 (Node.js)
+1. Ensure your BrightSign player supports Node.js applications.
+2. Copy both `javascript/autorun.brs` and `javascript/index.js` to the root of your SD card.
+3. Insert the SD card into your BrightSign player and power on (or restart if already running).
+4. The device will automatically reboot.
+5. Check the console output for the actual device IP address
+
+### Method 3 (Registry - Not recommended)
+1. Copy `registry-config/autorun.brs` to the root of your SD card.
+2. Insert the SD card into your BrightSign player and power on (or restart if already running).
+3. The script will automatically reboot the device for changes to take effect.
+4. Access the web interface at `https://<device-ip>/` (no password required with this method).
+5. Check the console output for the actual device IP address
+
+## Accessing the LDWS Web Interface
+
+Once LDWS is enabled:
+
+1. **Find the Device IP Address:**
+   - **Methods 1 & 2:** Check the console output after running the examples - the actual IP address will be displayed (see [BrightSign Shell documentation](https://docs.brightsign.biz/developers/brightsign-shell) for console access)
+   - **Alternative methods:** 
+     - Check your router's connected devices
+     - Boot the player without an SD card to see network information on screen
+     - Use the device serial number: navigate to `http://brightsign-<serial>.local` (replace `<serial>` with your device's serial number)
+
+2. **Access the Web Interface:**
+   - Open a web browser on a computer/laptop connected to the same network  
+   - Navigate to `https://<device-ip>/`; by default, the Diagnostic Web Server is enabled on port 80
+   - Enter the configured password when prompted (default: "your_password_here" for all examples)
+
+## Security Considerations
+
+- **Change Default Passwords:** Always use strong, unique passwords in production
+- **Network Security:** LDWS should only be enabled on trusted networks
+- **Access Control:** Consider network-level restrictions to limit access to the web interface
+- **Password Protection:** Methods 1 and 2 support password protection - use it
+
+## Troubleshooting
+
+- **Cannot Access Web Interface:**
+  - Verify the device IP address is correct
+  - Ensure your computer and BrightSign device are on the same network
+  - Check that the correct port is being used (default: 80)
+  - Verify the password is entered correctly
+
+- **Configuration Not Applied:**
+  - Method 1: Check if device rebooted after configuration
+  - Method 2: Ensure Node.js support is available on the device  
+  - Method 3: The device should automatically reboot - wait for restart to complete
+
+- **Port Conflicts:**
+  - If port 80 is in use by another application, choose a different port
+  - Update your browser URL to include the custom port number
+
+## Important Note: Registry Configuration (`dwse`)
+
+**Note:** The `dwse` registry key is only required for players that have been previously configured with a setup file that explicitly disabled LDWS. This registry setting is NOT needed when LDWS is simply disabled by default on the player. For standard LDWS enablement, use the `SetupDWS()` function (Method 1) or the `@brightsign/dwsconfiguration` module (Method 2) as these are the primary solutions for enabling LDWS functionality.
+
+## Best Practices
+
+1. **Use Method 1 (BrightScript)** for most BrightScript-based applications
+2. **Use Method 2 (Node.js)** when developing Node.js applications
+3. **Use strong passwords** and change them regularly
+4. **Document the LDWS password** for future reference
+5. **Test access** after configuration to ensure it works correctly
+6. **Disable LDWS** in production if not needed for ongoing maintenance
+
+This example provides a foundation for implementing LDWS configuration in your BrightSign applications using the method that best fits your development approach.

examples/enable-ldws-example/autorun.brs

@@ -0,0 +1,28 @@
+Sub Main()
+	' Create network configuration object (0 = eth0, 1 = wlan0, 2 = ppp0, usb0 and usb1 can be input as well)
+	nc = CreateObject("roNetworkConfiguration", 0)
+
+	' Configure LDWS: enable on port 80 with password
+	dwsConfig = { port: 80, open: "your_password_here" }
+
+	print "Enabling LDWS..."
+	rebootRequired = nc.SetupDWS(dwsConfig)
+	nc.Apply()
+
+	' Get device IP address to show user where to connect
+	currentConfig = nc.GetCurrentConfig()
+	if type(currentConfig) = "roAssociativeArray" then  
+		ipAddress$ = currentConfig.ip4_address  
+	else
+		ipAddress$ = "<device-ip>"
+	endif  
+
+	' Some configurations require restart to take effect
+	if rebootRequired then
+		print "Restarting device to apply changes..."
+		RebootSystem()
+	else
+		print "LDWS enabled! Access at: http://"; ipAddress$; "/"
+		print "Password: your_password_here"
+	end if
+End Sub

examples/enable-ldws-example/javascript/autorun.brs

@@ -0,0 +1,15 @@
+Sub Main()
+	print "Starting LDWS configuration..."
+
+	' Create message port to communicate with Node.js
+	mp = CreateObject("roMessagePort")
+	nodeApp = CreateObject("roNodeJs", "index.js", { message_port: mp })
+
+	' Event loop to handle Node.js messages
+	while true
+		msg = wait(0, mp)
+		if type(msg) = "roNodeJsEvent" then
+			print "Node.js: "; msg
+		end if
+	end while
+End Sub

examples/enable-ldws-example/javascript/index.js

@@ -0,0 +1,42 @@
+const DWSConfiguration = require("@brightsign/dwsconfiguration");
+const systemClass = require("@brightsign/system");
+const registryClass = require("@brightsign/registry");
+
+async function configureLDWS() {
+	console.log("Enabling LDWS...");
+	const system = new systemClass();
+	const registry = new registryClass();
+
+	// Create DWS configuration instance
+	const dwsConfig = new DWSConfiguration();
+	const config = {
+		port: 80,                    // HTTP port for web interface
+		password: {
+			value: "your_password_here",
+			obfuscated: false        // Password stored as plain text
+		},
+		authenticationList: ["digest"] // Use digest HTTP authentication
+	};
+
+	try {
+		const httpServerPort = await registry.read("networking", "http_server");
+		// Check if LDWS is already enabled
+		if (httpServerPort !== "" && httpServerPort !== "0") {
+			// LDWS is already enabled
+			console.log(`HTTP server port already set to ${httpServerPort}. LDWS may already be enabled.`);
+			return;
+		}
+
+		// Apply LDWS configuration to device
+		dwsConfig.applyConfig(config);
+		console.log("LDWS enabled!");
+
+		// Reboot device to apply changes
+		console.log("Rebooting device to apply changes...");
+		system.reboot();
+	} catch (error) {
+		console.error("Configuration failed:", error.message);
+	}
+}
+
+configureLDWS();

examples/enable-ldws-example/registry-config/autorun.brs

@@ -0,0 +1,26 @@
+function Main()
+	print "Enabling LDWS via registry..."
+
+	' Access the networking section of device registry
+	registrySection = CreateObject("roRegistrySection", "networking")
+
+	if type(registrySection) = "roRegistrySection" then
+
+		' Check if LDWS is already enabled
+		if registrySection.read("http_server") <> "" and registrySection.read("http_server") <> "0" then
+			print "HTTP server port already set. LDWS may already be enabled."
+		else if registrySection.read("dwse") = "yes" then
+			print "LDWS already enabled."
+		else 
+			' Set HTTP server to enable LDWS on the specified port
+			registrySection.write("http_server", "80")
+			' Enable Local DWS on the default port 80
+			' registrySection.write("dwse", "yes")
+			print "Registry updated - restart device"
+			print "After restart: http://<device-ip>/"
+			RebootSystem()
+		end if
+	else
+		print "Error: Could not access registry"
+	end if
+end function