feature request -- cli support for all functions in the API

[marc-portier]

The current cli.py functions as a nice introduction/example on how to use the library for very specific scripted automation needs. Actually example.py would probably be a better name, since it does not provide a full CLI coverage of all the functions provided by the library.

We could however introduce such coverage via a __main__.py

It should:

• be hooked up in the setup.py as a so called console-script 'entry-point' via setup( entry_points={'console_scripts'= ['pyamplipi = pyamplipi.__main__:main']})
• read recurring settings like AMPLIPI_API_URL and AMPLIPI_TIMEOUT from the environment through .env + python-dotenv
• allow to override those on the command line via -a «api_url» and -t «timeout»
• apply configurable logging
• provide consistent error-codes if things fail
• use argparse to cover all of the api via some smart design of the args:

pyamplipi [-a api_url] [-t timeout] TOPIC CMD ...

pyamplipi status list  # produces comprehensible output listing / overview
pyamplipi status get > output.json  
pyamplipi status set < input.json

pyamplipi source list  # produces comprehensible output listing / overview
pyamplipi source get «sourceid» | *  > output.json  # * wildcard for getting all
pyamplipi source set «sourceid» < update.json

pyamplipi zone list  # produces comprehensible output listing / overview
pyamplipi zone get «zoneid» | * > output.json
pyamplipi zone set «zoneid» < update.json

pyamplipi group list  # produces comprehensible output listing / overview
pyamplipi group get «groupid» | * > output.json
pyamplipi group set «groupid» < update.json
pyamplipi group new < input.json  # returns created groupid
pyamplipi group del «groupid» 

pyamplipi stream list  # produces comprehensible output listing / overview
pyamplipi stream get «streamid» | * > output.json
pyamplipi stream set «streamid» < update.json
pyamplipi stream new < input.json  # returns created groupid
pyamplipi stream del «groupid» 
pyamplipi stream play «groupid»  
pyamplipi stream pause «groupid»  
pyamplipi stream stop «groupid»  
pyamplipi stream next «groupid»  
pyamplipi stream prev «groupid»  

pyamplipi announce «media_url» [«vol_f»]  # plays the announcement

pyamplipi preset list  # produces comprehensible output listing / overview
pyamplipi preset get «presetid» | * > output.json
pyamplipi preset set «presetid» < update.json
pyamplipi preset load  «presetid» < input.json
pyamplipi preset new < input.json  # returns created presetid
pyamplipi preset del «presetid» 

note:

• edited the above after starting on this --> reordering CMD and TOPIC arguments turned out to implement more natural
• not all preset related endpoints are available in the library yet (might be a recent v0.1.9 ? addition) -- so those would need to be added too
• have to figure out the difference between set-preset PATCH /api/presets/{pid} and load-preset POST /api/presets/{pid}/load and how the CLI might maybe either hide or support both in the most natural way

I would be glad to provide a PR introducing the above as I see it a logical fit to what the lib is offering.

But I would also understand if you consider this as 'out of scope' and tell me to buzz off and implement this in a separate project.

[linknum23]

I think this sounds like a great idea. If we add this interface we would need to integrate it into some CI testing as well that is ran against a fake amplipi, in the past I have used jq for tests like this but pytest might be simpler and make more sense.

As for presets, the load function executes the partial change of state specified by the preset. So if the mute-all preset was loaded every zone would be muted when it was loaded and the api would return the full system status. So in your notation it would look like:

pyamplipi load preset «presetid» # produces comprehensible output listing / overview

[marc-portier]

ok, getting started on the branch to implement

including pytest is something I could surely do as well (have some experience with that -- in fact I would typically extend the Makefile hinted in #15 with a make test for that)

However -- against which actual service would you consider the tests to be executed?

To be clear: personally I would not want to have standard tests (including clearing config) to run against my running in house amplipi - do you guys have a standard mock or docker instance one can run on localhost to do this kind of stuff? Any other advise?

[marc-portier]

tracking my progress can be done over at --> main...marc-portier:pyamplipi:issue-16

• that will include stuff for install dependencies should get listed in the setup.py #6 Add CI that tests against several AmpliPi releases #12 introduce flake8 lint checking to help avoid programming errors and consistent styling #15 as well
• I will provide PR when wrapping up

[marc-portier]

While working on #16 I notice more missing features and altered models available on my local amplipi (v.0.1.9) compared to what is present in this library.

This is the same observation as was raised in #7 - the pull-request made available there (#11) is waiting to get merged on some testing for possible issues with other dependent libraries and systems ?

As I go along it looks like my branch for issue-16 is going to be facing the same limitations as it will be ontroducing more changes of a similar nature and possible impact.

Net effect to me is to also include that previous pull-request (#11) in this ongoing work and just close it.

[linknum23]

There have been a couple of changes to the API from 0.1.7 to 0.1.9, here is the full diff that github shows us: micro-nova/AmpliPi@0.1.7...0.1.9-uv-hotfix

API changes will be found in amplipi/app.py and amplipi/models.py. app.py defines the API endpoints and models.py defines the JSON models used by the API.

[linknum23]

At a quick glance here are the changes I see to the API (from appl.py):

• /api/factory_reset [POST]
• /api/reset [POST]
• /api/reboot [POST]
• /api/shutdown [POST]
• /api/info [GET]

For the json models (models.py) we added relative volume control, updated system information, and showed what stream commands were supported. Here is a little more detail:

• Info fields, including information on each of the preamp boards firmware
• for relative volume control vol_f was added to zone and groups, and for each zone a min and max volume (vol_min, vol_max) in dB can be specified to change the range of the relative volume adjustment.
• For source_info the field supported_cmds was added. This identifies what commands can be sent to a stream that is currently being played on a source. Stream commands are still a bit awkward, they need to be send via the /api/streams/{sid}/cmd endpoint.

I hope this helps!

[marc-portier]

thx for the explanations, @linknum23

the work is going well, and this helps completing what I am cooking up :)

Concerning the fact that the "info" part of the Status is really only read-only:
(meaning it is part of status-get, but is simply ignored in config-load)

I was thinking to create a split up of the models into

• the current Status (read) model and
• a distinct Config (write) model like this:

current:

class Status(BaseModel):
    sources: List[Source] = []
    zones: List[Zone] = []
    groups: List[Group] = []
    streams: List[Stream] = []
    presets: List[Preset] = []
    info: Optional[Info]

change to:

class Config(BaseModel):
    sources: List[Source] = []
    zones: List[Zone] = []
    groups: List[Group] = []
    streams: List[Stream] = []
    presets: List[Preset] = []
class Status(Config):
    info: Optional[Info]

wdyt?

[linknum23]

That sounds great. We could even change this in the AmpliPi repo.