PYNQ provides a Command Line Interface (CLI) that is used to offer some basic functionalities directly within a shell.
The way it works is pretty simple: when you are in a shell session, you can type
pynq subcommand
to execute whatever the selected subcommand is designed to do.
By itself, the pynq
root command is just a dispatcher: under the hood, when you type pynq subcommand
it looks for an available executable named pynq-subcommand
and runs it.
Therefore, to add new functionalities to the PYNQ CLI, it is sufficient to make a new executable available that follow this naming structure. For example, to manage instances of a device server, the pynq-server
executable is created, and it will be called by typing pynq server
in the command line.
You can get the associated help message by typing
pynq --help
This will print the help message with the available options, as well a list of the available subcommands.
To get the installed PYNQ version, you can type
pynq --version
This will also print out the hash of the commit ID from the PYNQ GitHub repository, that might be useful for diagnosing issues and bug reporting.
The pynq server
command is used to manage instances of device servers. You can either start
or stop
the server by typing the intended command as follows
pynq server start
And you can also get a help message by typing
pynq server --help
Note
As of now, we recommend not to use the pynq server
subcommand on Zynq and Zynq Ultrascale+ devices, as the device server in these cases is already managed by a system service provided in the PYNQ SD card image.
The pynq get-notebooks
command is responsible for the delivery of notebooks.
pynq get-notebooks
This command will create a pynq-notebooks
folder in your current working directory that will include notebooks and, possibly, associated overlays. The command will scan the environment for available notebooks coming from packages that have registered for discovery. You can read more about this mechanism in the pynq-python-packaging
section.
You may want to provide a specific path where to deliver the notebooks instead. You can achieve this by passing the --path
option
pynq get-notebooks --path <your-path>
By default, typing get-notebooks
without any option will deliver all the available notebooks and prompt the user for confirmation, listing what notebooks are detected and will be delivered. You can override this behavior by passing the special keyword all
to the command. This will deliver all the notebooks directly, without asking for confirmation
pynq get-notebooks all
You can also choose to get only a number of selected notebooks by typing the name of the notebooks you want
pynq get-notebooks nb1 [nb2 ...]
You can get a list of the available notebooks by using the --list
option
pynq get-notebooks --list
When running pynq get-notebooks
overlays are potentially downloaded automatically from the network based on the target device. Therefore, there is the possibility that some overlays will not be available for your device, and you will have to synthesize the manually from source. In case the overlays associated with certain notebooks are not found for your device, these notebooks will not be delivered. If, however, you want to get the notebooks anyway, ignoring the automatic overlays lookup, you can pass the --ignore-overlays
option.
pynq get-notebooks --ignore-overlays
Moreover, you can manually specify a target device by passing the --device
option
pynq get-notebooks --device DEVICE
Or get a list of detected devices to choose from using the --interactive
option instead.
pynq get-notebooks --interactive
The default behavior in case neither of these two options is passed, is to use the default device (i.e. pynq.Device.active_device
) for overlays lookup.
After the command has finished, you can run the notebooks examples by typing:
cd pynq-notebooks
jupyter notebook
The get-notebooks
command has a number of additional options that can be listed by printing the help message:
pynq examples --help
Please refer to the help message for more info about these options.