test, tools: introduce tbot README
introduce a README how to use tbot for testing U-Boot
and/or linux kernels.
Signed-off-by: Heiko Schocher <hs@denx.de>
diff --git a/tools/tbot/README.install b/tools/tbot/README.install
new file mode 100644
index 0000000..24c67bc
--- /dev/null
+++ b/tools/tbot/README.install
@@ -0,0 +1,370 @@
+# Copyright (c) 2016 DENX Software Engineering GmbH
+# Heiko Schocher <hs@denx.de>
+#
+# SPDX-License-Identifier: GPL-2.0+
+#
+
+install tbot on your PC (linux only tested):
+============================================
+
+- get the source code:
+
+$ git clone https://github.com/hsdenx/tbot.git
+[...]
+$
+
+ cd into the tbot directory.
+
+- you need the for running tbot the python paramiko module, see:
+ http://www.paramiko.org/installing.html
+
+ paramiko is used for handling ssh sessions, and open filedescriptors
+ on a ssh connection. Tbot open a ssh connection to a "lab PC" and
+ opens on that connection 2 filehandles, one for control functions
+ and one for the connection to the boards console. May it is worth
+ to think about to open more filehandles and use them in tbot, but
+ thats a point in the Todo list ...
+
+ See [1] for more infos about tbot principles.
+
+- prepare a directory for storing the logfiles
+ and pass it with the commandline option "-l"
+ to tbot. Default is the directory "log" in the tbot
+ root (don;t forget to create it, if you want to use it)
+
+- If your VL is not yet in tbot source, integrate it
+ (This task has only to be done once for your VL):
+
+ A VL has, as described in [2] "necessary tasks for a Lab PC" explained,
+ 3 tasks:
+
+ a) power on/off the board
+ b) get power state of the board
+ c) connect to the boards console
+
+ As tbot sends only shell commands (also to the Lab PC)
+ this tasks must be executable through shell commands on your
+ Lab PC:
+
+ Task a) power on/off board:
+ default TC for this task is:
+ https://github.com/hsdenx/tbot/blob/master/src/tc/tc_lab_denx_power.py
+
+ - now copy this file to for example
+ cp src/tc/tc_lab_denx_power.py src/tc/tc_lab_denx_power_XXX.py
+ (replace XXX to a proper value)
+ and adapt the "remote_power" command from the denx lab to your needs.
+
+ As this TC powers on the board for all your boards in your VL,
+ you can differ between the boards through the tbot class
+ variable "tb.boardlabpowername" (which is in the default case the
+ same as "tb.boardname"), but you may need to name the power target
+ with an other name than boardname, so you can configure this case.
+ The power state "tb.power_state" which the TC has to set
+ is "on" for power on, or "off" for power off.
+
+ If switching on the power is successful, call "tb.end_tc(True)"
+ else "tb.end_tc(False)"
+
+ - set in your board config file:
+ self.tc_lab_denx_power_tc = 'tc_lab_denx_power_XXX.py'
+
+ Task b) power on/off board:
+ default TC for this task is:
+ https://github.com/hsdenx/tbot/blob/master/src/tc/tc_lab_denx_get_power_state.py
+
+ - now copy this file to for example
+ (replace XXX to a proper value)
+ cp src/tc/tc_lab_denx_get_power_state.py src/tc/tc_lab_denx_get_power_state_XXX.py
+ and adapt the commands to your needs.
+
+ If the power of the board is on, call "tb.end_tc(True)"
+ else "tb.end_tc(False)"
+
+ - set in your board config file:
+ self.tc_lab_denx_get_power_state_tc = 'tc_lab_denx_get_power_state_XXX.py'
+
+ Task c) connect to the boards console:
+ default TC for this task is:
+ https://github.com/hsdenx/tbot/blob/master/src/tc/tc_lab_denx_connect_to_board.py
+
+ - now copy this file to for example
+ (replace XXX to a proper value)
+ cp src/tc/tc_lab_denx_connect_to_board.py src/tc/tc_lab_denx_connect_to_board_XXX.py
+ and adapt the commands to your needs.
+
+ As this TC powers on the board for all your boards in your VL,
+ you can differ between the boards through the tbot class
+ variable "tb.boardlabname" (which is in the default case the
+ same as "tb.boardname"), but you may need to name the power target
+ with an other name than boardname, so you can configure this case.
+
+ If connect fails end this TC with "tb.end_tc(False)"
+ else call "tb.end_tc(True)"
+
+ If you want to use kermit for connecting to the boards console, you
+ can use:
+
+ https://github.com/hsdenx/tbot/blob/master/src/tc/tc_workfd_connect_with_kermit.py
+
+ Example for such a board in the VL from denx:
+ self.tc_lab_denx_connect_to_board_tc = 'tc_workfd_connect_with_kermit.py'
+ https://github.com/hsdenx/tbot/blob/master/tbot_dxr2.cfg#L24
+
+ Hopefully this works for you too.
+
+ - set in your board config file:
+ self.tc_lab_denx_connect_to_board_tc = 'tc_lab_denx_connect_to_board_XXX.py'
+
+ remarks while writting this:
+ - Currently there is only the denx VL. Original idea was to include
+ other VL through a seperate class/file in
+ https://github.com/hsdenx/tbot/tree/master/src/lab_api
+ but it turned out, that if we say "ssh" is the standard way to connect
+ to a VL, we can integrate the VL specific tasks through testcases, see
+ above, so we should do:
+ - rename the "denx" API to a more general name.
+ This is a point on my ToDo list ... done, renamed to 'ssh_std'
+
+ - the VL specific configuration may moved from the board config files
+ and should be collected in VL specific config files, which boards
+ config file simple include.
+
+- prepare password.py file:
+ This file contains all passwords tbot needs (for example for
+ linux login on the boards)
+ tbot searches this file in the tbot root directory.
+ It is a simple python file, for example:
+
+ # passwords for the lab
+ if (board == 'lab'):
+ if (user == 'hs'):
+ password = 'passwordforuserhs'
+ if (user == 'root'):
+ password = 'passwordforrootuser'
+ # passwords for the boards
+ elif (board == 'mcx'):
+ if (user == 'root'):
+ password = 'passwordformcxrootfs'
+ else:
+ if (user == 'root'):
+ password = ''
+
+ In the above example passwords for logging into the Lab PC tbot finds
+ through:
+ if (board == 'lab'):
+ user = 'name':
+ password = 'gnlmpf' # password 'gnlmpf' for login of user 'name'
+
+- prepare board config file
+ Each board which is found in the VL needs a tbot configuration file
+ pass the config file name with the option '-c' to tbot, tbot searches
+ in the root dir for them.
+
+ board Example (dxr2 board):
+ https://github.com/hsdenx/tbot/blob/master/tbot_dxr2.cfg
+
+ Necessary variables:
+
+ line 3: boardname, here it is the "etamin" board
+ no default value, must be set.
+ line 4: boardlabname: name used for connecting to the board
+ may differ from tb.boardname, default tb.boardname
+ line 5: boardlabpowername: name used for power on/off
+ may differ from tb.boardname, default tb.boardname
+ line 6: tftpboardname: name used for tftp subdir (from where
+ U-Boot loads images for example).
+ may differ from tb.boardname, default tb.boardname
+ line 7: labprompt: linux prompt tbot sets
+ no defaultvalue, must be set (maybe we should introduce
+ "ttbott" as default ...
+ line 8: debug: If True, adds debug output on the tbot shell
+ line 9: debugstatus: enable status debug output on the shell
+ line 10: ip: Where tbot finds the Lab PC
+ line 11: user: As which user does tbot logs into the Lab PC
+ line 12: accept_all: passed to paramiko, accept all connections
+ line 13: keepalivetimout: passed to paramiko, timeout for sending
+ keepalive message.
+ line 14: channel_timeout: passed to paramiko
+ line 15: loglevel: tbots loglevel for adding entries into the logfile.
+ line 16: lap_api: used lap API (currently only 'ssh_std')
+ Should be declared as standard -> this line would be not needed
+ longer.
+ line 17: wdt_timeout: timeout in seconds for tbots watchdog.
+ Watchdog gets triggered if prompt get read.
+ line 20,21: include 'ssh_std' api
+ should be removed.
+ line 24: tc_lab_denx_connect_to_board_tc: Which TC is used for
+ connecting to the boards console the TC, here:
+ https://github.com/hsdenx/tbot/blob/master/src/tc/tc_workfd_connect_with_kermit.py
+ line 27: uboot_prompt: boards U-Boot prompt
+ line 28: linux_prompt: boards linux prompt
+
+ Now comes a list of variables TC needs, this vary from which TC
+ you start on the board.
+
+Thats it ... you now can call tbot and hopefully, it works ;-)
+Find an example log [3] for calling simple U-Boot TC for setting
+an U-Boot Environmentvariable.
+
+If you have problems in setting tbot up, please contact me
+(and may give me ssh access to your Lab PC ;-)
+
+If you have running your first TC [3], you may want to write now your own
+TC (and hopefully share them), so continue with:
+u-boot:tools/tbot/README.create_a_new_testcase
+
+Heiko Schocher <hs@denx.de>
+v1 2016.01.22
+
+--------------
+
+[1] tbot Dokumentation:
+ [2] u-boot:/tools/tbot/README
+ https://github.com/hsdenx/tbot/blob/master/README.md
+
+[3] Example for a first U-Boot TC which should always work:
+ (with commandline option "-v" for verbose output):
+
+hs@localhost:tbot [master] $ python2.7 src/common/tbot.py -c tbot_dxr2.cfg -t tc_ub_setenv.py -v -l log/tbot.log
+**** option cfg: tbot_dxr2.cfg log: log/tbot.log tc: tc_ub_setenv.py v 1
+('CUR WORK PATH: ', '/home/hs/data/Entwicklung/tbot')
+('CFGFILE ', 'tbot_dxr2.cfg')
+('LOGFILE ', '/home/hs/data/Entwicklung/tbot/log/tbot.log')
+(<denx.tbot_lab_api object at 0x7f53ac1808d0>, <tbotlib.tbot object at 0x7f53a45fd410>, True)
+(<denx.tbot_lab_api object at 0x7f53ac1808d0>, <tbotlib.tbot object at 0x7f53a45fd410>, True)
+read 0: Last login: Fri Jan 22 12:20:12 2016 from 87.97.28.177
+read 0:
+read 0: *************************************************************
+read 0: BDI2000 Assignment: (last updated: 2015-11-20 12:30 MET)
+read 0: bdi1 => techem bdi2 => cetec_mx25 bdi3 => lpc3250
+read 0: bdi4 => - bdi5 => --Rev.B!-- bdi6 => tqm5200s
+read 0: bdi7 => [stefano] bdi8 => smartweb bdi9 => sigmatek-nand
+read 0: bdi10 => pcm052 bdi11 => socrates bdi12 => aristainetos
+read 0: bdi13 => imx53 bdi14 => ib8315 bdi15 => cairo
+read 0: bdi16 => g2c1 bdi17 => lwe090 bdi18 => symphony
+read 0: bdi19 => dxr2 bdi20 => ima3-mx6 bdi21 => sama5d3
+read 0: bdi98 => - bdi99 => - bdi0 => -
+read 0: Please power off unused systems when you leave! Thanks, wd.
+read 0: *************************************************************
+read no ret 0:
+pollux:~ hs $
+write 0: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
+read 0: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
+read 0: hs@pollux [12:21:00] ttbott >
+read 1: Last login: Fri Jan 22 12:20:59 2016 from 87.97.28.177
+read 1:
+read 1: *************************************************************
+read 1: BDI2000 Assignment: (last updated: 2015-11-20 12:30 MET)
+read 1: bdi1 => techem bdi2 => cetec_mx25 bdi3 => lpc3250
+read 1: bdi4 => - bdi5 => --Rev.B!-- bdi6 => tqm5200s
+read 1: bdi7 => [stefano] bdi8 => smartweb bdi9 => sigmatek-nand
+read 1: bdi10 => pcm052 bdi11 => socrates bdi12 => aristainetos
+read 1: bdi13 => imx53 bdi14 => ib8315 bdi15 => cairo
+read 1: bdi16 => g2c1 bdi17 => lwe090 bdi18 => symphony
+read 1: bdi19 => dxr2 bdi20 => ima3-mx6 bdi21 => sama5d3
+read 1: bdi98 => - bdi99 => - bdi0 => -
+read 1: Please power off unused systems when you leave! Thanks, wd.
+read 1: *************************************************************
+read no ret 1:
+pollux:~ hs $
+write 1: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
+read 1: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
+read 1: hs@pollux [12:21:02] ttbott >
+write 0: remote_power dxr2 -l
+read 0: hs@pollux [12:21:00] ttbott >remote_power dxr2 -l
+read 0: dxr2 ON
+read 0: hs@pollux [12:21:02] ttbott >
+read no ret 1:
+hs@pollux [12:21:02] ttbott >
+write 1: ssh hs@lena
+read 1: ssh hs@lena
+read no ret 1:
+hs@lena's password:
+read 1:
+read 1: Last login: Fri Jan 22 12:20:17 2016 from 192.168.1.1
+read 1:
+read no ret 1:
+[hs@lena ~]$
+write 1: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
+read 1: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
+read 1: hs@lena [12:21:07] ttbott >
+read no ret 1:
+hs@lena [12:21:07] ttbott >
+write 1: stty cols 200
+read 1: stty cols 200
+read 1: hs@lena [12:21:08] ttbott >
+write 1: export TERM=vt200
+read 1: hs@lena [12:21:08] ttbott >export TERM=vt200
+read 1: hs@lena [12:21:08] ttbott >
+write 1: echo $COLUMNS
+read 1: hs@lena [12:21:08] ttbott >echo $COLUMNS
+read 1: 200
+read 1: hs@lena [12:21:08] ttbott >
+write 1: kermit
+read 1: hs@lena [12:21:08] ttbott >kermit
+read 1: C-Kermit 8.0.211, 10 Apr 2004, for Linux
+read 1:
+read 1: Copyright (C) 1985, 2004,
+read 1: Trustees of Columbia University in the City of New York.
+read 1: Type ? or HELP for help.
+read 1:
+read 1: (/home/hs/) C-Kermit>
+read 1:
+read no ret 1: (/home/hs/) C-Kermit>
+write 1: set line /dev/ttyUSB0
+read 1: set line /dev/ttyUSB0
+read 1:
+read 1: (/home/hs/) C-Kermit>
+write 1: set speed 115200
+read 1:
+read 1: (/home/hs/) C-Kermit>set speed 115200
+read 1: /dev/ttyUSB0, 115200 bps
+read 1:
+read 1: (/home/hs/) C-Kermit>
+write 1: set flow-control none
+read 1:
+read 1: (/home/hs/) C-Kermit>set flow-control none
+read 1:
+read 1: (/home/hs/) C-Kermit>
+write 1: set carrier-watch off
+read 1:
+read 1: (/home/hs/) C-Kermit>set carrier-watch off
+read 1:
+read 1: (/home/hs/) C-Kermit>
+write 1: connect
+read 1:
+read 1: (/home/hs/) C-Kermit>connect
+read 1: Connecting to /dev/ttyUSB0, speed 115200
+read 1:
+read 1: Escape character: Ctrl-\ (ASCII 28, FS): enabled
+read 1:
+read 1: Type the escape character followed by C to get back,
+read 1:
+read 1: or followed by ? to see other options.
+read 1:
+read 1: ----------------------------------------------------
+read no ret 1:
+
+write no ret 1:
+
+read 1:
+read 1: Heiko=Schocher
+read no ret 1:
+U-Boot#
+write no ret 1:
+write no ret 1:
+
+read 1: <INTERRUPT>
+read 1: U-Boot#
+write 1: setenv Heiko Schocher
+read 1: U-Boot# setenv Heiko Schocher
+read no ret 1:
+U-Boot#
+write 1: printenv Heiko
+read 1: printenv Heiko
+read 1: Heiko=Schocher
+read no ret 1:
+U-Boot#
+End of TBOT: success
+hs@localhost:tbot [master] $