psdb
====
This package provides Python access to various ARM-compatible debug probes.
All tools support the ``--help`` option. It is required to use python3. The
easiest way to install psdb is using pip::
pip3 install psdb
Note that you may wish to use sudo to install psdb for all users on your
system::
sudo pip3 install psdb
You may also install the package from the source using::
make install
which will require super-user privileges. Alternatively, you can run all
commands from the root of the repository without installing anything.
If you are on a Linux machine, it is also recommended to install the udev
rules file that will allow non-sudo access to the debug probes (otherwise you
must run the psdb tools using sudo) to anybody that is a member of the 'usb'
group::
sudo addgroup usb
sudo adduser YOUR_USER_NAME usb
sudo cp -r etc/* /etc/
This command is not necessary on macOS since USB devices are accessible
without super-user privileges. If your debug probe is connected when you
install the udev rules, you may need to hot-plug it in order for the new rules
to take effect. Also, if you just added yourself to the usb group then you
will need to start a new shell session for that permission to take effect.
psdb_flash_tool
===============
The flash_tool script allows you to burn ELF images into flash, retrieve the
contents of flash and reset a target board. On STM32, it is highly
recommended to use the ``--connect-under-reset`` option. This will reset the
target MCU and halt in the reset handler before any code has a chance to
execute and potentially interfere with the flashing operation. This is
especially important on the STM32WB series where the flash is shared by the
wireless coprocessor. Non-STM32 MCUs may not support connecting to the target
while it is under reset (for instance, the MSP432 does not support this).
To dump the full flash contents to a file, generating a raw binary image
(useful for making a backup of the original flash contents on a board)::
psdb_flash_tool --connect-under-reset --read path/to/file.bin
To write a raw binary image into flash::
psdb_flash_tool --connect-under-reset --write--raw-binary path/to/file.bin
Flashing of ELF and Intel HEX files is also supported. In these cases, all
address ranges that overlap with the flash will be burnt in, and other address
ranges will be ignored. Note that the target sectors (and only the target
sectors) are fully erased first, so any sectors that are under-specified in
the ELF or HEX files will contain 0xFF in the unused regions. To flash an ELF
or HEX file::
psdb_flash_tool --connect-under-reset --flash path/to/image.elf
psdb_flash_tool --connect-under-reset --flash path/to/image.hex
Finally, erasing the flash is also supported. All writeable sectors will be
erased to the value 0xFF::
psdb_flash_tool --connect-under-reset --erase
The flash_tool script can also be used to view and modify the STM32 option
bytes stored in the MCU's flash. The ``--get-options`` flag allows one to dump
the contents of all option bytes::
psdb_flash_tool --connect-under-reset --get-options
While the ``--option`` argument (which takes two parameters - a
case-insensitive option name and an option value) can be specified multiple
times to change options::
psdb_flash_tool --connect-under-reset --option nboot1 0 --option nboot0 1
psdb_core_tool
==============
The core_tool script can be used to capture the contents of flash and SRAM in
the form of an ELF core file. This core file, in conjunction with the
original ELF executable, can be opened under gdb for offline diagnosis.
Unfortunately, the standard ``arm-none-eabi-gdb`` tool cannot open core files;
however, ``gdb-multiarch`` is able to open these without any trouble. On Linux,
this is as simple as installing ``gdb-multiarch`` with your package manager.
On other systems, installing in a Docker container may be a viable alternative.
The ``--peripheral-capture`` option allows the capture of all registers from
devices listed in the target's dev array.
The captured core file is independent of the build system used to generate the
executable or the actual code installed on the microcontroller. To debug the
core file::
gdb-multiarch path/to/executable.elf
target core path/to/core.elf
psdb_gdb_tool
=============
The gdb_tool script starts a simple gdb server that attaches to the target
device. It can be connected to with a remote gdb client.
psdb_inspect_tool
=================
The inspect_tool script starts an interactive curses-based tool that can be
used to view the current CPU registers, select target peripheral registers and
select regions of target RAM or flash. The inspect_tool script requires the
tgcurses library to be installed (available on github/tgree). pip will
install tgcurses automatically.
psdb_fus_tool
=============
The fus_tool script is for interacting with the ST Firmare Upgrade Services
(FUS) on the STM32WB55 wireless MCU. The STM32WB55 co-processor has a secure
region of flash that includes the FUS binary itself and the wireless stack
currently installed on the MCU. Different wireless stacks can be installed
and FUS itself can also be upgraded. The binaries can be found in ST's
`STM32CubeWB.git`_ repository under the path::
Projects/STM32WB_Copro_Wireless_Binaries/STM32WB5x
Sample invocations for manipulating wireless firmware::
psdb_fus_tool --fw-upgrade Projects/STM32WB_Copro_Wireless_Binaries/STM32WB5x/stm32wb5x_BLE_Stack_full_fw.bin
psdb_fus_tool --fw-delete
Or, a compound command to remove the old WS firmware, install new WS firmware
and then start the application back up::
psdb_fus_tool \
--fw-delete \
--fw-upgrade Projects/STM32WB_Copro_Wireless_Binaries/STM32WB5x/stm32wb5x_BLE_Stack_full_fw.bin \
--set-flash-boot
Note that an invocation with ``--set-flash-boot`` is required when you are done;
in order to properly communicate with FUS, we need to prevent any user
firmware from starting CPU2 or trying to use the IPC channels - we do that by
switching the system to boot from SRAM1 until we are done with it.
When using this to upgrade FUS itself, you use the ``--fus-upgrade`` option
along with the ``--bin-dir`` option. The code will find the next valid FUS
binary in the upgrade path for your target. For instance, a brand new Nucleo
STM32WB55 board has an ancient 0.5.3 version of FUS. This cannot be directly
upgraded to the latest 1.1.0 version of FUS but must instead stop at 1.0.2
first. You can then reinvoke fus_tool again if you wish to then upgrade from
1.0.2 to 1.1.0. Note that it is not possible to downgrade FUS, so this
behavior allows you to stop at any desired version. When upgrading FUS, it is
required to first delete the current wireless stack with the ``--fw-delete``
option.
Sample invocation for updating FUS::
psdb_fus_tool --bin-dir Projects/STM32WB_Copro_Wireless_Binaries/STM32WB5x --fus-upgrade
Note that when upgrading FUS, the target board will reboot at least 4 times.
It is recommended to upgrade to FUS 1.1.0.
STLINK Protocol
===============
We also attempt to document the STLINK protocol inside the stlink package.
You can view it most easily from within the python interpreter::
>>> import psdb.probes.stlink
>>> help(psdb.probes.stlink.cdb)
.. _STM32CubeWB.git: https://github.com/STMicroelectronics/STM32CubeWB
Raw data
{
"_id": null,
"home_page": "https://github.com/tgree/psdb",
"name": "psdb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.0",
"maintainer_email": null,
"keywords": "stlink xds110 arm swd fus stm32 msp432",
"author": "Terry Greeniaus",
"author_email": "terrygreeniaus@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9c/88/7a9b1b441c2096c093847475d68153004f756c6db5351c7c2353bfc185c7/psdb-1.1.4.tar.gz",
"platform": null,
"description": "psdb\n====\nThis package provides Python access to various ARM-compatible debug probes.\n\nAll tools support the ``--help`` option. It is required to use python3. The\neasiest way to install psdb is using pip::\n\n pip3 install psdb\n\nNote that you may wish to use sudo to install psdb for all users on your\nsystem::\n\n sudo pip3 install psdb\n\nYou may also install the package from the source using::\n\n make install\n\nwhich will require super-user privileges. Alternatively, you can run all\ncommands from the root of the repository without installing anything.\n\nIf you are on a Linux machine, it is also recommended to install the udev\nrules file that will allow non-sudo access to the debug probes (otherwise you\nmust run the psdb tools using sudo) to anybody that is a member of the 'usb'\ngroup::\n\n sudo addgroup usb\n sudo adduser YOUR_USER_NAME usb\n sudo cp -r etc/* /etc/\n\nThis command is not necessary on macOS since USB devices are accessible\nwithout super-user privileges. If your debug probe is connected when you\ninstall the udev rules, you may need to hot-plug it in order for the new rules\nto take effect. Also, if you just added yourself to the usb group then you\nwill need to start a new shell session for that permission to take effect.\n\n\npsdb_flash_tool\n===============\nThe flash_tool script allows you to burn ELF images into flash, retrieve the\ncontents of flash and reset a target board. On STM32, it is highly\nrecommended to use the ``--connect-under-reset`` option. This will reset the\ntarget MCU and halt in the reset handler before any code has a chance to\nexecute and potentially interfere with the flashing operation. This is\nespecially important on the STM32WB series where the flash is shared by the\nwireless coprocessor. Non-STM32 MCUs may not support connecting to the target\nwhile it is under reset (for instance, the MSP432 does not support this).\n\nTo dump the full flash contents to a file, generating a raw binary image\n(useful for making a backup of the original flash contents on a board)::\n\n psdb_flash_tool --connect-under-reset --read path/to/file.bin\n\nTo write a raw binary image into flash::\n\n psdb_flash_tool --connect-under-reset --write--raw-binary path/to/file.bin\n\nFlashing of ELF and Intel HEX files is also supported. In these cases, all\naddress ranges that overlap with the flash will be burnt in, and other address\nranges will be ignored. Note that the target sectors (and only the target\nsectors) are fully erased first, so any sectors that are under-specified in\nthe ELF or HEX files will contain 0xFF in the unused regions. To flash an ELF\nor HEX file::\n\n psdb_flash_tool --connect-under-reset --flash path/to/image.elf\n psdb_flash_tool --connect-under-reset --flash path/to/image.hex\n\nFinally, erasing the flash is also supported. All writeable sectors will be\nerased to the value 0xFF::\n\n psdb_flash_tool --connect-under-reset --erase\n\nThe flash_tool script can also be used to view and modify the STM32 option\nbytes stored in the MCU's flash. The ``--get-options`` flag allows one to dump\nthe contents of all option bytes::\n\n psdb_flash_tool --connect-under-reset --get-options\n\nWhile the ``--option`` argument (which takes two parameters - a\ncase-insensitive option name and an option value) can be specified multiple\ntimes to change options::\n\n psdb_flash_tool --connect-under-reset --option nboot1 0 --option nboot0 1\n\n\npsdb_core_tool\n==============\nThe core_tool script can be used to capture the contents of flash and SRAM in\nthe form of an ELF core file. This core file, in conjunction with the\noriginal ELF executable, can be opened under gdb for offline diagnosis.\nUnfortunately, the standard ``arm-none-eabi-gdb`` tool cannot open core files;\nhowever, ``gdb-multiarch`` is able to open these without any trouble. On Linux,\nthis is as simple as installing ``gdb-multiarch`` with your package manager.\nOn other systems, installing in a Docker container may be a viable alternative.\n\nThe ``--peripheral-capture`` option allows the capture of all registers from\ndevices listed in the target's dev array.\n\nThe captured core file is independent of the build system used to generate the\nexecutable or the actual code installed on the microcontroller. To debug the\ncore file::\n\n gdb-multiarch path/to/executable.elf\n target core path/to/core.elf\n\n\npsdb_gdb_tool\n=============\nThe gdb_tool script starts a simple gdb server that attaches to the target\ndevice. It can be connected to with a remote gdb client.\n\n\npsdb_inspect_tool\n=================\nThe inspect_tool script starts an interactive curses-based tool that can be\nused to view the current CPU registers, select target peripheral registers and\nselect regions of target RAM or flash. The inspect_tool script requires the\ntgcurses library to be installed (available on github/tgree). pip will\ninstall tgcurses automatically.\n\n\npsdb_fus_tool\n=============\nThe fus_tool script is for interacting with the ST Firmare Upgrade Services\n(FUS) on the STM32WB55 wireless MCU. The STM32WB55 co-processor has a secure\nregion of flash that includes the FUS binary itself and the wireless stack\ncurrently installed on the MCU. Different wireless stacks can be installed\nand FUS itself can also be upgraded. The binaries can be found in ST's\n`STM32CubeWB.git`_ repository under the path::\n\n Projects/STM32WB_Copro_Wireless_Binaries/STM32WB5x\n\nSample invocations for manipulating wireless firmware::\n\n psdb_fus_tool --fw-upgrade Projects/STM32WB_Copro_Wireless_Binaries/STM32WB5x/stm32wb5x_BLE_Stack_full_fw.bin\n psdb_fus_tool --fw-delete\n\nOr, a compound command to remove the old WS firmware, install new WS firmware\nand then start the application back up::\n\n psdb_fus_tool \\\n --fw-delete \\\n --fw-upgrade Projects/STM32WB_Copro_Wireless_Binaries/STM32WB5x/stm32wb5x_BLE_Stack_full_fw.bin \\\n --set-flash-boot\n\nNote that an invocation with ``--set-flash-boot`` is required when you are done;\nin order to properly communicate with FUS, we need to prevent any user\nfirmware from starting CPU2 or trying to use the IPC channels - we do that by\nswitching the system to boot from SRAM1 until we are done with it.\n\nWhen using this to upgrade FUS itself, you use the ``--fus-upgrade`` option\nalong with the ``--bin-dir`` option. The code will find the next valid FUS\nbinary in the upgrade path for your target. For instance, a brand new Nucleo\nSTM32WB55 board has an ancient 0.5.3 version of FUS. This cannot be directly\nupgraded to the latest 1.1.0 version of FUS but must instead stop at 1.0.2\nfirst. You can then reinvoke fus_tool again if you wish to then upgrade from\n1.0.2 to 1.1.0. Note that it is not possible to downgrade FUS, so this\nbehavior allows you to stop at any desired version. When upgrading FUS, it is\nrequired to first delete the current wireless stack with the ``--fw-delete``\noption.\n\nSample invocation for updating FUS::\n\n psdb_fus_tool --bin-dir Projects/STM32WB_Copro_Wireless_Binaries/STM32WB5x --fus-upgrade\n\nNote that when upgrading FUS, the target board will reboot at least 4 times.\n\nIt is recommended to upgrade to FUS 1.1.0.\n\n\nSTLINK Protocol\n===============\nWe also attempt to document the STLINK protocol inside the stlink package.\nYou can view it most easily from within the python interpreter::\n\n >>> import psdb.probes.stlink\n >>> help(psdb.probes.stlink.cdb)\n\n\n.. _STM32CubeWB.git: https://github.com/STMicroelectronics/STM32CubeWB\n",
"bugtrack_url": null,
"license": "LGPLv2",
"summary": "Package for interfacing with ARM-compatible debug probes",
"version": "1.1.4",
"project_urls": {
"Homepage": "https://github.com/tgree/psdb"
},
"split_keywords": [
"stlink",
"xds110",
"arm",
"swd",
"fus",
"stm32",
"msp432"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a511cf9afca076733ecff7f4bf2971ec8af8a1e5332e408b6f6da8983053008",
"md5": "d4937f37f157887ca423346f3b41631f",
"sha256": "a9d34bf4d68e95515337406a1b5f62d4547846b36a0f6b1b74903ef1a10deaae"
},
"downloads": -1,
"filename": "psdb-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4937f37f157887ca423346f3b41631f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.0",
"size": 264794,
"upload_time": "2024-04-21T04:25:54",
"upload_time_iso_8601": "2024-04-21T04:25:54.377119Z",
"url": "https://files.pythonhosted.org/packages/9a/51/1cf9afca076733ecff7f4bf2971ec8af8a1e5332e408b6f6da8983053008/psdb-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9c887a9b1b441c2096c093847475d68153004f756c6db5351c7c2353bfc185c7",
"md5": "790e111ac18c28da0049cccbdf17c309",
"sha256": "b1161edeef25b7990392f801e13c88801904df3498ae6ca29cd044f2b4667138"
},
"downloads": -1,
"filename": "psdb-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "790e111ac18c28da0049cccbdf17c309",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.0",
"size": 193406,
"upload_time": "2024-04-21T04:25:56",
"upload_time_iso_8601": "2024-04-21T04:25:56.615411Z",
"url": "https://files.pythonhosted.org/packages/9c/88/7a9b1b441c2096c093847475d68153004f756c6db5351c7c2353bfc185c7/psdb-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-21 04:25:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tgree",
"github_project": "psdb",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "psdb"
}
JSON
