Warning
THIS CODEBASE IS DEPRECATED! bsc version 2.0.0 is now hosted here
The purpose of this package is to allow users to communicate with the BrightSign's Local DWS (Diagnostic Web Server) REST HTTP APIs through a simple CLI tool, bsc.
Install from NPM,
npm install -g @brightsign/bscadd a player,
bsc addplayer <playerName> <ipAddress> [username] [password] [storage]
bsc getdi <playerName>
- Interact with a BrightSign player on your local network
- Push files to a player
- Edit registry settings of a player
- Get device info, registry dumps, logs and files from a player
- Get and set a player's time
- Reboot or factory reset a player
- Change the DWS password of a player
- Other miscellaneous features that the DWS frontend provides, but from the command line
bsc is available as an npm package, and can also be built from the code in this repository.
This CLI is available on npm. To install it, run the following command:
npm install -g @brightsign/bscFirst, clone this repository to your preferred location. Once cloned, navigate to the directory that you stored this code in.
It is assumed you have the requirements for doing basic node.js development already installed. To support this example, you also need to run the following in this folder:
npm installThe following will need to be run to build the npm module. bsc will be built and ready to use.
npm -g installAfter installing, run bsc --help without arguments to see usage options:
Command usage: bsc <command> [options]
Commands:
bsc getdi <playerName> Get Device Info
bsc addplayer <playerName> <ipAddress> Add a player
[username] [password] [storage]
bsc rmplayer <playerName> remove a player
bsc editplayer <playerName> Update a player
bsc listplayers List all players
bsc reboot <playerName> Reboot a player
bsc checkpw <playerName> Check if player has a lDWS password
bsc setpw <playerName> [newPassword] Change player lDWS password, enter
"" for no password
bsc screenshot <playerName> Take a screenshot
bsc getlogs <playerName> Get logs
bsc raw allow for raw input
bsc delfile <playerName> <file> Delete a file
bsc putfile <playerName> <FileDirectory> Put files on a player
[location]
bsc getfiles <playerName> [path] Get files on player
bsc downloadfile <playerName> [path] Download file on player
bsc gettime <playerName> Get player time
bsc settime <playerName> <timezone> Set player time
<time> <date> [applyTimezone]
bsc checkdws <playerName> Check if player has DWS enabled
bsc setdws <playerName> <onOff> set DWS on/off
bsc getreg <playerName> [section] [key] Get registry values
bsc setreg <playerName> <section> <key> Edit registry values
<value>
bsc setpowersave <playerName> Set the video connector power save
<connector> <device> <value>
bsc getpowersave <playerName> Get the video connector power save
<connector> <device>
bsc facreset <playerName> Factory reset player
Options:
--version Show version number [boolean]
-v, --verbose Run with verbose logging [boolean] [default: false]
-d, --rawdata Output raw json response data [boolean] [default: false]
-h, --help Show help [boolean]
Add a player,
bsc addplayer <playerName> <ipAddress> [username] [password] [storage]For ease of use this CLI has introduced a locally stored player configuration object. This object stores relevant player information under a "playerName" (that you choose, independent of the player's name in BACon, bDeploy, or any other service where player names are required), allowing the player to be interacted with at the command line by just using the player name. This configuration object is stored in a hidden directory on your home directory path, or ~/.bsc/players.json, and is automatically generated when you use the CLI.
When you first try and use a command, if you have not configured the CLI for at least one player, the command will not be run and instead you will be prompted to configure your first player. Simply enter the name you want to give to your player, the ip address, the username and the password of the player, and the player's storage device. Remember that by default, the player's digest authentication username is 'admin' and the password is the serial number. Additionally, the CLI will automatically set the username to 'admin' and the storage device to 'sd' if those fields are left blank.
Once the CLI has generated the player configuration object, you can freely add, remove and edit the players stored within it.
You can remove players from your configuration with:
bsc rmplayer <playerName>
And you can edit a player's properties with:
bsc editplayer <playerName> -p password -i ipaddress -u username -s storage
Note here that none of the options are required but all can be changed at once.
Finally, to view your configuration file and the properties of each player, use:
bsc listplayers
{
"exampleName": {
"ipAddress": "sss.sss.sss.sss",
"username": "admin",
"password": "password",
"storage": "sd"
}
}If you store a hidden file called .players.json in your current working directory, the CLI will prioritize that over the player storage stored in ~/.bsc. This allows for easier organization of players and a much less cluttered players.json main file.
Note to use file upload, the password must not be set on the player. You can easily turn off the password using setpw or from the lDWS front end. This is a WIP and this doc will be updated when this functionality exists.
bsc addplayersThis CLI uses a player configuration object to interact with your player(s). To configure the CLI to interact with a player, refer to configuring players locally.
A list of commands and their structure can be seen by typing bsc, bsc -h or bsc --help. There's also a table of the currently supported features and their command structure below in the features section. All commands (except raw and listplayers) use a 'playerName'. This is the name that you set in players.json. Some commands use 'positionals', or options that must be in a certain spot. These positionals are shown in the 'help' section and on the features table. Positionals listed with <> are required and ones with [] are optional. Certain commands also have options. Options are not defined by position but rather by a tag, for example bsc editplayer playerName -i newIP. In that example the new IP address is the option, defined by '-i'. Options can be in whatever order you want. For information on a command and its options, use bsc command with no positionals or options.
Sometimes you will run into errors while using this CLI. The CLI has built in error handling that should give you information on the error you encountered as well as troubleshooting tips. However, the error handler does not have info on every possible error, so you may run into errors that are not handled. If this is the case, there are certain troubleshooting steps that you can walk through to hopefully fix your problem.
- Check that you can communicate with the player
- Is the player on? Is the DWS on?
- Is the player on the same LAN as you?
- When you make a request with the CLI, does it show in the player's logs?
- Check your local player info
- Use
bsc listplayers. Does that info look right? - Use
bsc checkpw playerName. This will return information about your local password and the password on the player - Did you input the correct playerName?
- Use
- Check the Github issues page
- Maybe others have ran into this before
- If none of these work, and your own troubleshooting methods also fail, please open a Github issue and/or a Jira issue (under the PE project, linked to PE-52) with reproduction steps.
Note: We ask that if you encounter an error that is not handled by the error handler (if the error is an API error, the error handler will tell you if it doesn't have info on your error. If it's another type of error, that error will be printed on you command line) that you open a Github issue and report it. This will allow the dev team to implement error handling around your error.
| Feature | Implemented? | Function | Usage |
|---|---|---|---|
| addplayer | [x] | Add player configuration to players.json | bsc addplayer <playerName> <ipAddress> [lDWS username] [lDWS password] |
| rmplayer | [x] | Remove player configuration from players.json | bsc rmplayer <playerName> |
| editplayer | [x] | Edit an already existing player's info | bsc editplayer <playerName> -i [playerIP] -u [playerUsername] -p [playerPassword] |
| listPlayers | [x] | List players and their configuration in players.json | bsc listplayers |
| getdi | [x] | Get device info in the form of a JSON object | bsc getdi <playerName> |
| putfile | [x] | Put file/files on a player. Specify a single file or a directory of files and the upload location (optional). Note that this only works when the player does not have a password set. The location option is exclusively a directory, not the filename it will be stored as | bsc putfile <playerName> <File/Directory> [location] |
| getfiles | [x] | get the files on the player's storage or in a certain directory | bsc getfiles <playerName> [path] |
| delfile | [x] | Delete a file on the player | bsc delfile <playerName> <path> |
| reboot | [x] | Reboot the specified player | bsc reboot <playerName> |
| checkpw | [x] | Check if lDWS password is enabled | bsc checkpw <playerName> |
| setpw | [x] | Change the DWS password, both locally and on the player | bsc setpw <playerName> [newPassword] |
| screenshot | [x] | Take a screenshot | bsc screenshot <playerName> |
| raw | [x] | Make API requests 'raw', not using the locally configured players | bsc raw -i <targetIP> -p [targetPassword] -m <requestMethod> -r <requestRoute> -a [rawResponseBool] -f [file] |
| settime | [x] | Set the player's time | bsc settime <playerName> <timezone> <time> <date> [applyTimezone] |
| gettime | [x] | Get the player's time | bsc gettime <playerName> |
| checkdws | [x] | Check if the DWS is enabled or not | bsc checkdws <playerName> |
| setdws | [x] | Toggles DWS on/off | bsc setDWS <playerName> <on/off> |
| getlogs | [x] | Gets logs from the player and puts them in a local file | bsc getlogs <playerName> |
| facreset | [x] | Factory resets the player | bsc facreset <playerName> |
| getreg | [x] | Gets the registry | bsc getreg <playerName> [section] [key] |
| setreg | [x] | Edits certain sections of the registry | bsc editreg <playerName> <section> <key> <value> |
bsc also supports raw API requests:
bsc raw -i <targetIp> -p [targetPassword] -m <reqMethod> -r <reqRoute> -a [rawResponse]
For example:
bsc raw -i=192.168.128.148 -p=ABC01A000001 -m=GET -r="info"
bsc raw -i=192.168.128.148 -p=ABC01A000001 -m=GET -r="files/sd"
Push a file with raw command:
bsc raw -i=192.168.128.148 -p=ABC01A000001 -m=PUT -r="files/sd" -f="PATH"
Install the tool jq to prettify the JSON response structures.
Parse the keys:
bsc raw -a=true -i=192.168.128.101 -p=ABC01A000001 -m=GET -r="info" | jq 'keys'Prettify the entire response:
bsc raw -a=true -i=192.168.128.101 -p=XAE28N000058 -m=GET -r="info" | jq '.data.result'Parse the model from /info
bsc raw -a=true -i=192.168.128.101 -p=ABC01A000001 -m=GET -r="info" | jq '.data.result.model'