`tbottest.generic`

This is an example approach for a hopefully easy to use lab and board support.

Therefore we use ini file based configuration, based on

https://docs.python.org/3/library/configparser.html

with all its limitiations.

But it showed, that for a first use of tbot, it is easier to explain to edit a tbot.ini file and start!

requirements for lab host

Commands that need root rights on the lab host (setting up the board’s ethernet device, mounting an SD card, sd-mux, imx_usb, uuu, installing packages) run with sudo when tbot is logged in to the lab host as a normal user; sudo then has to work without entering a password. When tbot is logged in as root, they run without sudo, so a lab host without sudo (for example one built with Yocto) works as well. tbottest asks id -u once per machine, see tbottest.tc.common.lnx_sudo(). Use it in your own testcases instead of a fixed sudo:

from tbottest.tc.common import lnx_sudo

lab.exec0(*lnx_sudo(lab), "mkdir", "-p", path)

Commands you write into tbot.ini yourself (e.g. labinit) are run as written, so leave out sudo there on a lab host you log in to as root.

You should be able to ssh between lab host, build host and board without entering a password or something else!

supported hardware/tools

Console access to the board with:

picocom, see [PICOCOM_BOARDNAME]
kermit, see [KERMIT_BOARDNAME]
telnet, see [TELNET_BOARDNAME]
a script of your own, see [SCRIPTCOM_BOARDNAME]
ssh into the running Linux of the board, flag ssh

Power control with:

sispmctl, see [SISPMCTRL_BOARDNAME]
Tinkerforge, see [TF_BOARDNAME]
a GPIO pin, see [GPIOPMCTRL_BOARDNAME]
a shell script, see [POWERSHELLSCRIPT_BOARDNAME]
a Shelly device through shelly-ctrl, see [SHELLY_BOARDNAME]
a tbox SYSTEM Controller Modul through tbox-ctrl (USB HID), see [TBOX_BOARDNAME]
the DH electronics TM-021 relay module, see [TM021_BOARDNAME]

Loading SPL/U-Boot after power on, or a debugger, with:

uuu from NXP, see setup for uuu tool
dfu-util, see setup for dfu-util tool
sb, xmodem/ymodem over the serial line, see setup for sb tool
Lauterbach TRACE32, see setup for Lauterbacher debugger
Segger J-Link, see setup for Segger debugger
Abatron BDI2000, commands after power on and a telnet session, see setup for BDI2000 debugger

It should be easy to extend this! tbot does not prevent you to use other hardware (nor to make stupid stuff)!

configuration

Create a directory, e.g. tbotsetup, which holds the sources of tbot and tbottest and a subdirectory tbotconfig with all your project specific settings and testcases. The layout, file by file, is in file/directory overview; the example is tbottest/tbotconfig.

Note

You can simply use the script create_setup.sh in scripts, which will create all files and directories. Start it with the option “–inter” and you get asked some questions, which help to make a better basic setup.

$ ./scripts/create_setup.sh --inter

start script

with the newbot_starter.py script you can start tbot and your setup without the need to install tbot and tbottest.

tbotconfig

contains the whole lab and board configuration.

README

README.BOARDNAME is not mandatory, but it is helpfull to collect/document at least some tbot usecases/commands.

file/directory overview

What scripts/create_setup.sh sets up, with tbotconfig for one board:

tbotsetup/
├── setup.sh                     aliases for starting tbot (source setup.sh)
├── tbot/                        tbot, from github.com/Rahix/tbot, with tbottest/patches applied
├── tbottest/                    this repository; newtbot_starter.py starts tbot
└── tbotconfig/                  your own repository: configuration and testcases
    ├── interactive.py           testcases for interactive sessions
    ├── ci/                      testcases of the tbottest CI on github (only with --ci)
    ├── tc_BOARDNAME.py          testcases of the board
    └── BOARDNAME/
        ├── args/                argumentfiles
        │   ├── argsbase
        │   ├── argsBOARDNAME
        │   ├── argsBOARDNAME-noeth
        │   └── argsBOARDNAME-noeth-ssh
        ├── boardspecific.py     runtime adaptions of the configuration
        ├── BOARDNAME.ini        settings of the board for the testcases
        ├── files/
        │   └── dumpfiles/       files of the register dump testcases
        ├── README.BOARDNAME     notes on the tbot setup of the board
        └── tbot.ini             lab host, build hosts, console, power, ...

files and directories
Name	content	fastlink to documentation
setup.sh	aliases for starting tbot	tbottest/tbotconfig/setup.sh
tbotconfig/interactive.py	testcases for interactive sessions: lab host, build host, kas shell, board, U-Boot, Linux, BDI2000
tbotconfig/ci	testcases the github CI of tbottest runs; create_setup.sh copies them only with `--ci`
tbotconfig/tc_BOARDNAME.py	testcases of the board, from tbottest/tbotconfig/BOARDNAME/BOARDNAME.py
BOARDNAME/args	argumentfiles: argsbase, argsBOARDNAME, and the variants -noeth (flags noethinit, noboardethinit) and -noeth-ssh (adds nopoweroff, always-on, ssh, nouboot)	argumentfiles
BOARDNAME/boardspecific.py	functions that adapt the configuration at runtime, e.g. replace the @@…@@ placeholders	boardspecfic runtime adaptions
BOARDNAME/BOARDNAME.ini	ini file with the board specific settings for the generic testcases	boardconfiguration file
BOARDNAME/files/dumpfiles	reference files of the register dump testcases (lnx_dump_files in BOARDNAME.ini)
BOARDNAME/README.BOARDNAME	notes on the tbot setup of the board, not mandatory
BOARDNAME/tbot.ini	ini file for lab host, build hosts and how tbot reaches and controls the board	tbot ini file (tbot.ini)
BOARDNAME/tbot.ini-<id>, BOARDNAME/BOARDNAME.ini-<id>	copies tbot writes at every start, with the placeholders replaced; flag tmpfilepath:<dir> writes them elsewhere	tbot flags

tbot ini file (tbot.ini)

we use for configuring lab and board settings with:

https://docs.python.org/3/library/configparser.html

Find an example file here: tbottest/tbotconfig/BOARDNAME/tbot.ini

Currently there are the following sections in tbot.ini:

[LABHOST]

here you configure common lab host setting. Mandatory.

You can select between ssh key login or password login into the lab host.

For login with ssh key set key ‘sshkeyfile’, for password login set key ‘password’.

[LABHOST]
key	value	example
labname	name of your lab	lab7
hostname	hostname of lab host	192.168.1.123
username	username on lab host	pi
port	ssh port number	22
sshkeyfile	path to the ssh keyfile, tbot uses	/home/USERNAME/.ssh/id_rsa
password	set password to login into lab host	FooBar
date	subdirectory in boards tftp path	20210803-ml
shelltype	type of the linux shell (bash\|ash)	bash
toolsdir	where does tbot find tools installed on lab host	/home/USERNAME/source
tftproot	rootpath to tftp directory on lab host. tbot stores there build results.	/srv/tftpboot
tftpsubdir	boards subdir in tftproot	BOARD/DATE
workdir	tbots workdirectory on lab host	/work/USERNAME/tbot-workdir/BOARD
tmpdir	path to where tbot stores temporary data	/tmp/tbot/USERNAME/BOARD
testdir	optional, path where testcases install or build things on the lab host, default workdir/tbottests	/work/USERNAME/tbot-workdir/BOARD/tbottests
proxyjump	if set, proxyjump settings for ssh login on lab host	pi@xeidos.ddns.net
labinit	array of strings which contains commands, executed when you init the lab. They run once per boot of the lab host, marked by /tmp/tbotlabinitdone; the setup of the board’s ethernet devices on the lab host runs once per board, marked by /tmp/tbotlabinitdone-<boardname>. Remove a marker to run its part again	[‘sudo systemctl –all –no-pager restart tftpd-hpa’]
nfs_base_path	base path to nfs share on lab host. !! May you have board specific subdir, so use placeholder @@TBOTLABBASENFSPATH@@ in board ini file and replace it in set_board_cfg	/srv/nfs
uselocking	use board locking mechanism. You must pass correct locking id for the board with tbot flag lablocking:<lockingid> else tbot will fail.	yes\|no

The above labhost defintion is the default one, You can add more than one labhost, simply add them with the following section naming

[LABHOST_<NAME_OF_LAB>]

You can now select this lab by adding tbot flag

-f labname:<NAME_OF_LAB>

on start of tbot.

[BUILDHOST]

here you configure common build host setting. Only used, if you use a buildhost.

[BUILDHOST]
key	value	example
name	name of your build host	threadripper-big-build
username	username on your build host	hs
hostname	hostname of your build machine	192.168.1.120
port	portnumber of your build machine	12004
docker	porxy jump configuration	hs@192.168.1.120:22
dl_dir	for yocto builds, sets DL_DIR	/work/downloads
sstate_dir	for yocto builds, set SSTATE_DIR	/work2/hs/tbot2go/yocto-sstate
kas_ref_dir	when using kas, path where kas finds git trees for reference cloning	/work/hs/src
workdir	path to directory where tbot can work on	/work/big/hs/tbot2go
testdir	optional, path where testcases install or build things on the build host, e.g. an SDK, default workdir/tbottests	/work/big/hs/tbot2go/tbottests
authenticator	path to ssh id key file	/home/hs/.ssh/id_rsa
password	password for ssh login. Unsure!	CrazyPassword
initcmd	list of commands executed after login	[“uname -a”, “cat /etc/os-release”]

If you do not add authenticator or password, tbot uses NoneAuthenticator for ssh login. Hopefully than your ssh config is correct.

The above buidlhost defintion is the default one, You can add more than one buildhost, simply add them with the following section naming

[BUILDHOST_<NAME_OF_BUILDER>]

You can now select this builder by adding tbot flag

-f buildname:<NAME_OF_BUILDER>

on start of tbot.

The next sections depend on your board configuration

[BOOTMODE_BOARDNAME]

if you need to set a bootmode for your board, you can add this section.

You can give each bootmode a name and if you pass this name to tbot with the “-f” flag, the lab approach first sets all gpios you have defined for this bootmode to the respective states, before it powers on the board.

Find more information in

tbottest.labgeneric.GenericLab.set_bootmode()