CLI Documentation Questions

Daksol commented 2 months ago

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'

michaelherger commented 2 months ago

Thanks for looking into all this, @Daksol! Alas, it can be overwhelming... It would be easier to follow up if you had one question per issue, or if you posted one question per thread in the forums. Here you have at least two totally independent questions, with a lot of information...

So in short: the id I don't know, really. Might be something from CometD. But in my JSON/RPC requests I always put 1 and don't care. I believe in theory it would allow to link the response to a request, as they can be out of sync in CometD. But with JSON/RPC that's not the case, therefore probably irrelevant for that use case.

As for the playerindex: I never used that. I mean... how would you know which player you're dealing with? I'm pretty sure that's a legacy thing nobody bothers to use that way. We should probably remove it from the documentation and consistently use the playerid instead (MAC address).

player <id> something also sounds like legacy. We should always suggest the <id> player something syntax.

Daksol commented 2 months ago

OK thanks, will ensure one question per comment.

Let me restate the issue with the player <subcommand> ? only using playerid as identifier.

Using Syntax-2: player <subcommand> <playerid> ?
- Responses are accurate
Using Syntax-4: <playerid> player <subcommand> ?
- You get a response but it is not accurate. Info returned when querying any of the players is same - equal to that for the particular player with playerindex = 0. In the output query above the query response for Syntax-3 and Syntax-4 is always the same as that for the Squeezelite-X player which has playerindex = 0

Daksol commented 2 months ago

I have a Python script which runs the whole thing, can share that if useful.

Meantime here is the CURL version, should work once you have correct IP and port STEP 1 - Ensure you have at least two players connected. Three or more makes it more obvious.

STEP 2 - Run this command to get the current players and their mac addresses

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["-",["players", "0"]]}' http://192.168.5.75:9005/jsonrpc.js

STEP 3 - Take the mac addresses of first three players and put them into the code below. There are two commands (as per my syntax-2, syntax-4 from above) for each player,

If for the second and subsequent players you see different responses from the two syntax commands - then problem demonstrated.

STEP 3-0: playerindex=0, 98:2c:bc:18:e1:06

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["-",["player", "name", "98:2c:bc:18:e1:06", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["98:2c:bc:18:e1:06",["player", "name", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

STEP 3-1: Playerindex=1, 00:04:20:28:c7:f1

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["-",["player", "name", "00:04:20:28:c7:f1", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["00:04:20:28:c7:f1",["player", "name", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

STEP 3-2: Playerindex=2, 00:04:20:12:ae:f5

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["-",["player", "name", "00:04:20:12:ae:f5", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["00:04:20:12:ae:f5",["player", "name", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

Daksol commented 2 months ago

Markup of the curl queries indicating where the two different syntaxes of the player name get a different response except for player with playerindex=0

curl

michaelherger commented 2 months ago

You should look at the code where those functions are registered. The decision to have player with and without the requirement for a client certainly is a legacy. But it's clearly defined in the registration call whether the client is required as the first parameter or not. See eg. https://github.com/LMS-Community/slimserver/blob/public/9.0/Slim/Control/Request.pm#L466-L472 - there's the "requires Client" column (parameter).

michaelherger commented 1 week ago

@Daksol I just learned that the favorites commands/queries were not documented here. Should they be part of one of the existing sections?

edgar-vincent commented 1 week ago

I'd be happy to help add the favorites commands after I have familiarised myself with the way the website is structured and built.

LMS-Community / lms-community.github.io