Setup and Requirements

Requirements

The requirements for your platform consist of the platform-specific requirements (either Windows or Linux) and the general requirements below.

Windows

• tested OS version: Windows 10 (amd64)
• tested Python versions: Python 3.10.7 and 3.12.0 (64bit); used Python distribution: PythonBuilds

Linux

• tested OS version: Ubuntu 22.04 (amd64); limited testing was also performed with Manjaro (Arch) Linux (amd64)
• tested Python version: Python 3.10.7 and 3.12.0 (64bit); used Python distribution: PythonBuilds

General

Segger J-Link

• Segger J-Link debug probe or STM32 eval board with ST-Link converted to J-Link
• Segger J-Link Software Pack. Notice: The following version should be avoided since they have known issues related to SRAM download: v6.50, v6.52(a-c).

Recommended

• STM32F072 Nucleo-64 board which is used as reference platform for the examples coming with DOTT.

PE Micro

As of DOTT version 1.10, first support for P&E Micro debug probes has been added via P&E's gdb server which is shipped free of charge as part of P&E's Eclipse plugin. Note that P&E Micro support in DOTT has not yet undergone as in-depth testing as support for Segger debug probes.

Building the P&E runtime extension for DOTT can be done by cloning the DOTT repository and executing the following commands:

# Linux example
$ python -m venv venv_setup
$ . venv_setup/bin/activate
$ pip install setuptools wheel twine
$ cd <YOUR_DOTT_CHECKOUT_PATH>
$ python setup.py bdist_wheel --dott-runtime-pemicro-s32k

The result of the steps above is a Pyhton package in the dist folder called dott_ng_pemicro_s32k_runtime-5.7.5-py3-none-any.whl (or similar). This package contains the P&E GDB server and support for files for NXP S32K MCUs. If you need support for other MCUs change setup.py accordingly.

Note that the P&E DOTT runtime file needs to be generated by users themselves and is not provided via PyPi.

For Linux systems, a udev rule similar to the following one might be needed for P&E Micro OpenSDA debuggers:

# PE Micro OpenSDA
# This file should be installed to /etc/udev/rules.d so that you can access the PE Micro hardware without being root
# e.g., /etc/udev/rules.d/99-PEMicro.rules
 
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="1357", ATTR{idProduct}=="0089", MODE="0666"

Compiler and Test Equipment (Optional)

• Arm GNU toolchain to re-build the example firmware images.
• GNU Make to re-build the example firmware images.
• RaspberryPi as test equipment to, e.g., provide stimuli via I2C or SPI to the system under test.

Setup Instructions

The setup instructions for your platform consist of the platform-specific instructions (either Windows or Linux) and the general instructions below.

Windows

• There are currently no Windows-specific setup steps.

Linux

• Make sure that the following packages are installed:

  $ sudo apt-get install libpython2.7 libncurses5

  General

• Download and install the Segger J-Link software to its default location. The default location is automatically searched by DOTT and it automatically selects the most recent of the installed JLink software versions.
• In case your are installing to a non-default location or want to select a particular JLink software version, set the DOTTJLINKPATH environment variable to point to the location of this JLink software version.
• If you are using the recommended STM32F072 Nucleo-64 reference board, convert its ST-LINK debugger to a J-Link debugger by the instructions from the DOTT documentation.
• It is assumed that you have a Python interpreter installed. DOTT is currently tested using version 3.10 but should also work with 3.8.
• It is recommended (but not required) to create and activate a virtual environment for DOTT:

  # Windows
  $ python -m venv dott_venv
  $ dott_venv\Scripts\activate.bat
   
  # Linux
  $ python -m venv dott_venv
  $ . dott_venv/bin/activate

• DOTT can be installed using pip from the official Python Package Index (pypi):

  $ pip install dott-ng

• Some troubleshooting notes (mostly for Ubuntu Linux):
  • If, during pip install, you are seeing error messages such as ‘invalid command 'bdist_wheel’orFailed building wheel for ..., run the following command and then re-run thepip installcommand from above. ``shell script $ pip install setuptools wheel twine ``
  • If, duringpip install, you are seeing error messages such asfatal error: Python.h: No such file or directory, install the Python development package using the following command: ``shell script $ apt-get install python3-dev ```
• If you are using a requirements.txt you can include DOTT as follows:

  ...
  dott-ng
  ...

• This installs all the required dependencies including the dott-ng-runtime package. The dott-ng-runtime contains binary dependencies required by DOTT. This is the GNU debugger (GDB) client for Arm Cortex-M processors (together with its dependencies) as distributed by Arm in the GNU Arm Embedded Toolchain.
• Download the zip archive with documentation and example projects from the DOTT releases website and unpack it to your disk.
• Make sure that the STM32F072 Nucleo-64 board is connected to your PC and that its ST-LINK is already converted to J-Link. Open a shell (and activate the DOTT virtual environment if you are using venv). Next, execute the example tests from the zip file:

  # Windows
  $ cd examples\01_component_testing\host
  $ pytest
   
  # Linux
  $ cd examples/01_component_testing/host
  $ pytest

• This should generate an output similar to the one below. This indicates that you have correctly installed DOTT and successfully executed your first tests. Please consult the DOTT documentation to learn more about basic component testing as in this example as well as about more advanced system testing concepts.

  [INFO] dott.py @197: DOTT runtime:          c:\tmp\venv_dott_install_test/dott_data (package-internal)
  [INFO] dott.py @198: DOTT runtime version:  package-internal
  [INFO] dott.py @201: work directory:        C:\tmp\dott_ng_doc_examples_20191217\examples
  [INFO] dott.py @246: BL ELF (load):         None
  [INFO] dott.py @254: BL ELF (symbol):       None
  [INFO] dott.py @262: BL ADDR (symbol):      0x0
  [INFO] dott.py @268: APP ELF (load):        01_component_testing/target/build/dott_example_01/dott_example_01.bin.elf
  [INFO] dott.py @275: APP ELF (symbol):      01_component_testing/target/build/dott_example_01/dott_example_01.axf
  [INFO] dott.py @279: Device name:           STM32F072RB
  [INFO] dott.py @286: Device endianess:      little
  [INFO] dott.py @290: J-LINK interface:      SWD
  [INFO] dott.py @294: J-LINK speed (set):    15000
  [INFO] dott.py @306: GDB client binary:     c:\tmp\venv_dott_install_test/dott_data/apps/gdb/bin/arm-none-eabi-gdb-py
  [INFO] dott.py @314: GDB server address:    10.10.171.84
  [INFO] dott.py @320: GDB server port:       2331
  [INFO] dott.py @344: GDB server assumed to be already running (not started by DOTT).
  [INFO] dott.py @390: Std. target mem model for DOTT default fixtures:  TargetMemModel.TESTHOOK
  [INFO] fixtures.py @46: Triggering download of APP to FLASH...
  PASSED                                                                                                                                                   [  4%]
  test_example_functions.py::TestExampleFunctions::test_example_NoArgsStatic PASSED                                                                        [  9%]
  test_example_functions.py::TestExampleFunctions::test_example_Addition PASSED                                                                            [ 14%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionPtr PASSED                                                                         [ 19%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionPtr_Alternate PASSED                                                               [ 23%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionPtr_AlternateArray PASSED                                                          [ 28%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionPtrRet PASSED                                                                      [ 33%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionPtrRet_Alternate PASSED                                                            [ 38%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionStruct PASSED                                                                      [ 42%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionStruct_Alternate PASSED                                                            [ 47%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionStruct_ctypes PASSED                                                               [ 52%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionStructPtr PASSED                                                                   [ 57%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionStructPtr_Alternate PASSED                                                         [ 61%]
  test_example_functions.py::TestExampleFunctions::test_example_ManyArgs PASSED                                                                            [ 66%]
  test_example_functions.py::TestExampleFunctions::test_example_CustomOperation PASSED                                                                     [ 71%]
  test_example_functions.py::TestExampleFunctions::test_example_ArgString PASSED                                                                           [ 76%]
  test_example_functions.py::TestExampleFunctions::test_example_SumElements PASSED                                                                         [ 80%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionSubcalls PASSED                                                                    [ 85%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionSubcallsBasicIntercept PASSED                                                      [ 90%]
  test_example_functions.py::TestExampleFunctions::test_example_AdditionSubcallsExtIntercept PASSED                                                        [ 95%]
  test_example_functions.py::TestExampleFunctions::test_global_data_access PASSED                                                                          [100%]
   
  -------------------- generated xml file: C:\tmp\dott_ng_doc_examples_20191217\examples\test_results.xml ---------------------
  ===================================================================== 21 passed in 10.41s =====================================================================