CLI Documentation Questions

Command line interface - CLI commands documentation

Some (not high priority) issues which came up when doing some further testing of the CLI - done mostly with the intention of generating some more examples, particularly JSONRPC ones, which are (IMHO) heaps easier to read.

PURPOSE OF ID PARAMETER WITH JSONRPC ?

See JSONRPC section of Using the CLI
Question about the "id" parameter for JSONRPC. In the JSONRPC notes for use by CURL etc, one of the parameters passed is "id" (along with "params" and "method"). I realise that when running the commmands via JSON I have not included "id" and it still seems to work.

What is its function? - maybe to allow the response to multiple JSONRPC calls to be easily distinnguished?

---

PLAYER COMMAND INCONSISTENCIES

I was doing some followup checking on behaviour of certain CLI commands for Players.

The command players provides full info about all connected players; this works fine, documentation is inline with behaviour.

There is also group of eight commands like "player name" which return a specific piece of info about a particular player.
The subcommands are: name, uuid, displaytype, id, ip, model, isplayer, canpoweroff

These commands have more than one format to achieve the same result - based on the documentation and examples given. The variants are wrt the parameter used (playerid or playerindex) and where the parameter is placed (as a pre-pended player identifier or after the 'player ' bit).

Syntax Options with Player identifier after the player <subcommand> string

• SYNTAX-1 player name <playerindex> ?
• SYNTAX-2 player name <playerid> ?

where <playerid> is (usually) the player's MAC address, and <playerindex> is a sequence number assigned to players currently recognised by the server, with values like 0, 1, 2 etc

Syntax options where Player identifier precedesthe player <subcommand> string

Some places in the documentation it is shown that these two forms are also permissable.

• SYNTAX-3 <playerindex> player name ?
• SYNTAX-4 <playerid> player name ?

See for instance syntax and examples for player name

Testing results

All of these formats (SYNTAX-1 thru -4) "work" in that they return a result; but I noticed some discrepancies.

So we need to test all four formats for eight subcommands for four players (as one does).

• used all four SYNTAX options as above
• used all eight subcommands (name, uuid, displaytype, id, ip, model, isplayer, canpoweroff)
• while having four players connected (one squeezelite, two Sb Radios one SB Classic v3)

And compared the results with what comes back from the players command

Result of this testing is that SYNTAX-3, and SYNTAX-4 while they work (in that a result is returned) do not provide an accurate response. They seem to always return information about the player currently with Index 0.

Suggested actions:

• Remove any use of Syntax-3 or Syntax-4 from the documentation, including the Examples
• Include a cautionary note

@mherger - Your call as whether this should be raised as a bug?

Number of players: 4
Info on all players from the players command
0 {'playerindex': '0', 'playerid': '98:2c:bc:18:e1:06', 'uuid': None, 'ip': '192.168.5.22:60888', 'name': 'Squeezelite-X', 'seq_no': 0, 'model': 'squeezelite', 'modelname': 'Squeezelite-X', 'power': 1, 'isplaying': 0, 'displaytype': 'none', 'isplayer': 1, 'canpoweroff': 1, 'connected': 1, 'firmware': 'v1.9.9-1419'}
1 {'playerindex': 1, 'playerid': '00:04:20:28:c7:f1', 'uuid': 'ca1c8fbf2d48cbb1c859b5ea7ce4ecf9', 'ip': '192.168.5.102:56551', 'name': 'Stalking Horse', 'seq_no': '12', 'model': 'baby', 'modelname': 'Squeezebox Radio', 'power': 1, 'isplaying': 0, 'displaytype': 'none', 'isplayer': 1, 'canpoweroff': 1, 'connected': 1, 'firmware': '8.0.1-r16924'}
2 {'playerindex': 2, 'playerid': '00:04:20:12:ae:f5', 'uuid': None, 'ip': '192.168.5.103:47742', 'name': 'Dittography', 'seq_no': 0, 'model': 'squeezebox3', 'modelname': 'Squeezebox Classic', 'power': 1, 'isplaying': 0, 'displaytype': 'graphic-320x32', 'isplayer': 1, 'canpoweroff': 1, 'connected': 1, 'firmware': 137}
3 {'playerindex': 3, 'playerid': '00:04:20:2a:e0:74', 'uuid': '7147ee259b66f5c9c39c0eb14cfefb5c', 'ip': '192.168.5.101:53614', 'name': 'Runcible Red', 'seq_no': '220', 'model': 'baby', 'modelname': 'Squeezebox Radio', 'power': 1, 'isplaying': 0, 'displaytype': 'none', 'isplayer': 1, 'canpoweroff': 1, 'connected': 1, 'firmware': '8.0.1-r16924'}
****************************************

Now testing the 'player <subcommand>' set of commands giving info on individual players
Subcommands to test are: ['canpoweroff', 'displaytype', 'id', 'ip', 'isplayer', 'model', 'name', 'uuid']

Subcommand      Syntax 1              Syntax 2              Syntax 3              Syntax 4             
--------------- --------------------- --------------------- --------------------- ---------------------
PLAYER Index:0 ID:98:2c:bc:18:e1:06  Name:Squeezelite-X

canpoweroff     1                     1                     1                     1                    
displaytype     none                  none                  none                  none                 
id              98:2c:bc:18:e1:06     98:2c:bc:18:e1:06     98:2c:bc:18:e1:06     98:2c:bc:18:e1:06    
ip              192.168.5.22:60888    192.168.5.22:60888    192.168.5.22:60888    192.168.5.22:60888   
isplayer        1                     1                     1                     1                    
model           squeezelite           squeezelite           squeezelite           squeezelite          
name            Squeezelite-X         Squeezelite-X         Squeezelite-X         Squeezelite-X        
uuid            None                  None                  None                  None                 
*******************************************************************************************************
PLAYER Index:1 ID:00:04:20:28:c7:f1  Name:Stalking Horse

canpoweroff     1                     1                     1                     1                    
displaytype     none                  none                  none                  none                 
id              00:04:20:28:c7:f1     00:04:20:28:c7:f1     98:2c:bc:18:e1:06     98:2c:bc:18:e1:06    
ip              192.168.5.102:56551   192.168.5.102:56551   192.168.5.22:60888    192.168.5.22:60888   
isplayer        1                     1                     1                     1                    
model           baby                  baby                  squeezelite           squeezelite          
name            Stalking Horse        Stalking Horse        Squeezelite-X         Squeezelite-X        
uuid            ca1c8fbf2d48cbb1c...  ca1c8fbf2d48cbb1c...  None                  None                 
*******************************************************************************************************
PLAYER Index:2 ID:00:04:20:12:ae:f5  Name:Dittography

canpoweroff     1                     1                     1                     1                    
displaytype     graphic-320x32        graphic-320x32        none                  none                 
id              00:04:20:12:ae:f5     00:04:20:12:ae:f5     98:2c:bc:18:e1:06     98:2c:bc:18:e1:06    
ip              192.168.5.103:47742   192.168.5.103:47742   192.168.5.22:60888    192.168.5.22:60888   
isplayer        1                     1                     1                     1                    
model           squeezebox2           squeezebox2           squeezelite           squeezelite          
name            Dittography           Dittography           Squeezelite-X         Squeezelite-X        
uuid            None                  None                  None                  None                 
*******************************************************************************************************
PLAYER Index:3 ID:00:04:20:2a:e0:74  Name:Runcible Red

canpoweroff     1                     1                     1                     1                    
displaytype     none                  none                  none                  none                 
id              00:04:20:2a:e0:74     00:04:20:2a:e0:74     98:2c:bc:18:e1:06     98:2c:bc:18:e1:06    
ip              192.168.5.101:53614   192.168.5.101:53614   192.168.5.22:60888    192.168.5.22:60888   
isplayer        1                     1                     1                     1                    
model           baby                  baby                  squeezelite           squeezelite          
name            Runcible Red          Runcible Red          Squeezelite-X         Squeezelite-X        
uuid            7147ee259b66f5c9c...  7147ee259b66f5c9c...  None                  None                 
*******************************************************************************************************

UUID values truncated to 17 chars to keep the table pretty.
UUID values of None (the Python key word indicating a nullvalue) shown as the string 'None'