diff --git a/examples/enable-ldws-example/README.md b/examples/enable-ldws-example/README.md new file mode 100644 index 0000000..46eccfc --- /dev/null +++ b/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:///` (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-.local` (replace `` 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:///`; 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. diff --git a/examples/enable-ldws-example/autorun.brs b/examples/enable-ldws-example/autorun.brs new file mode 100644 index 0000000..5d40d6c --- /dev/null +++ b/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$ = "" + 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 diff --git a/examples/enable-ldws-example/javascript/autorun.brs b/examples/enable-ldws-example/javascript/autorun.brs new file mode 100644 index 0000000..4c74a5a --- /dev/null +++ b/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 diff --git a/examples/enable-ldws-example/javascript/index.js b/examples/enable-ldws-example/javascript/index.js new file mode 100644 index 0000000..17ee5a1 --- /dev/null +++ b/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(); \ No newline at end of file diff --git a/examples/enable-ldws-example/registry-config/autorun.brs b/examples/enable-ldws-example/registry-config/autorun.brs new file mode 100644 index 0000000..392388d --- /dev/null +++ b/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:///" + RebootSystem() + end if + else + print "Error: Could not access registry" + end if +end function \ No newline at end of file