tools/tbot/README.install

   1 # Copyright (c) 2016 DENX Software Engineering GmbH
   2 # Heiko Schocher <hs@denx.de>
   3 #
   4 # SPDX-License-Identifier:      GPL-2.0+
   5 #
   6
   7 install tbot on your PC (linux only tested):
   8 ============================================
   9
  10 - get the source code:
  11
  12 $ git clone https://github.com/hsdenx/tbot.git
  13 [...]
  14 $
  15
  16   cd into the tbot directory.
  17
  18 - you need the for running tbot the python paramiko module, see:
  19   http://www.paramiko.org/installing.html
  20
  21   paramiko is used for handling ssh sessions, and open filedescriptors
  22   on a ssh connection. Tbot open a ssh connection to a "lab PC" and
  23   opens on that connection 2 filehandles, one for control functions
  24   and one for the connection to the boards console. May it is worth
  25   to think about to open more filehandles and use them in tbot, but
  26   thats a point in the Todo list ...
  27
  28   See [1] for more infos about tbot principles.
  29
  30 - prepare a directory for storing the logfiles
  31   and pass it with the commandline option "-l"
  32   to tbot. Default is the directory "log" in the tbot
  33   root (don;t forget to create it, if you want to use it)
  34
  35 - If your VL is not yet in tbot source, integrate it
  36   (This task has only to be done once for your VL):
  37
  38   A VL has, as described in [2] "necessary tasks for a Lab PC" explained,
  39   3 tasks:
  40
  41   a) power on/off the board
  42   b) get power state of the board
  43   c) connect to the boards console
  44
  45   As tbot sends only shell commands (also to the Lab PC)
  46   this tasks must be executable through shell commands on your
  47   Lab PC:
  48
  49   Task a) power on/off board:
  50     default TC for this task is:
  51     https://github.com/hsdenx/tbot/blob/master/src/tc/tc_lab_denx_power.py
  52
  53     - now copy this file to for example
  54       cp src/tc/tc_lab_denx_power.py src/tc/tc_lab_denx_power_XXX.py
  55       (replace XXX to a proper value)
  56       and adapt the "remote_power" command from the denx lab to your needs.
  57
  58       As this TC powers on the board for all your boards in your VL,
  59       you can differ between the boards through the tbot class
  60       variable "tb.boardlabpowername" (which is in the default case the
  61       same as "tb.boardname"), but you may need to name the power target
  62       with an other name than boardname, so you can configure this case.
  63       The power state "tb.power_state" which the TC has to set
  64       is "on" for power on, or "off" for power off.
  65
  66       If switching on the power is successful, call "tb.end_tc(True)"
  67       else "tb.end_tc(False)"
  68
  69     - set in your board config file:
  70       self.tc_lab_denx_power_tc = 'tc_lab_denx_power_XXX.py'
  71
  72   Task b) power on/off board:
  73     default TC for this task is:
  74     https://github.com/hsdenx/tbot/blob/master/src/tc/tc_lab_denx_get_power_state.py
  75
  76     - now copy this file to for example
  77       (replace XXX to a proper value)
  78       cp src/tc/tc_lab_denx_get_power_state.py src/tc/tc_lab_denx_get_power_state_XXX.py
  79       and adapt the commands to your needs.
  80
  81       If the power of the board is on, call "tb.end_tc(True)"
  82       else "tb.end_tc(False)"
  83
  84     - set in your board config file:
  85       self.tc_lab_denx_get_power_state_tc = 'tc_lab_denx_get_power_state_XXX.py'
  86
  87   Task c) connect to the boards console:
  88     default TC for this task is:
  89     https://github.com/hsdenx/tbot/blob/master/src/tc/tc_lab_denx_connect_to_board.py
  90
  91     - now copy this file to for example
  92       (replace XXX to a proper value)
  93       cp src/tc/tc_lab_denx_connect_to_board.py src/tc/tc_lab_denx_connect_to_board_XXX.py
  94       and adapt the commands to your needs.
  95
  96       If connect fails end this TC with "tb.end_tc(False)"
  97       else call "tb.end_tc(True)"
  98
  99       If you want to use kermit for connecting to the boards console, you
 100       can use:
 101
 102       https://github.com/hsdenx/tbot/blob/master/src/tc/tc_workfd_connect_with_kermit.py
 103
 104       Example for such a board in the VL from denx:
 105       self.tc_lab_denx_connect_to_board_tc = 'tc_workfd_connect_with_kermit.py'
 106       https://github.com/hsdenx/tbot/blob/master/tbot_dxr2.cfg#L24
 107
 108       Hopefully this works for you too.
 109
 110     - set in your board config file:
 111       self.tc_lab_denx_connect_to_board_tc = 'tc_lab_denx_connect_to_board_XXX.py'
 112
 113   remarks while writting this:
 114   - Currently there is only the denx VL. Original idea was to include
 115     other VL through a seperate class/file in
 116     https://github.com/hsdenx/tbot/tree/master/src/lab_api
 117     but it turned out, that if we say "ssh" is the standard way to connect
 118     to a VL, we can integrate the VL specific tasks through testcases, see
 119     above, so we should do:
 120     - rename the "denx" API to a more general name.
 121       This is a point on my ToDo list ... done, renamed to 'ssh_std'
 122
 123   - the VL specific configuration may moved from the board config files
 124     and should be collected in VL specific config files, which boards
 125     config file simple include.
 126
 127 - prepare password.py file:
 128   This file contains all passwords tbot needs (for example for
 129   linux login on the boards)
 130   tbot searches this file in the tbot root directory.
 131   It is a simple python file, for example:
 132
 133   # passwords for the lab
 134   if (board == 'lab'):
 135       if (user == 'hs'):
 136           password = 'passwordforuserhs'
 137       if (user == 'root'):
 138           password = 'passwordforrootuser'
 139   # passwords for the boards
 140   elif (board == 'mcx'):
 141       if (user == 'root'):
 142           password = 'passwordformcxrootfs'
 143   else:
 144       if (user == 'root'):
 145           password = ''
 146
 147 - prepare board config file
 148   Each board which is found in the VL needs a tbot configuration file
 149   pass the config file name with the option '-c' to tbot, tbot searches
 150   in the root dir for them.
 151
 152   board Example (dxr2 board):
 153   https://github.com/hsdenx/tbot/blob/master/tbot_dxr2.cfg
 154
 155   Necessary variables:
 156
 157   line  3: boardname, here it is the "etamin" board
 158              no default value, must be set.
 159   line  4: boardlabname: name used for connecting to the board
 160              may differ from tb.boardname, default tb.boardname
 161   line  5: boardlabpowername: name used for power on/off
 162              may differ from tb.boardname, default tb.boardname
 163   line  6: tftpboardname: name used for tftp subdir (from where
 164              U-Boot loads images for example).
 165              may differ from tb.boardname, default tb.boardname
 166   line  7: labprompt: linux prompt tbot sets
 167              no defaultvalue, must be set (maybe we should introduce
 168              "ttbott" as default ...
 169   line  8: debug: If True, adds debug output on the tbot shell
 170   line  9: debugstatus: enable status debug output on the shell
 171   line 10: ip: Where tbot finds the Lab PC
 172   line 11: user: As which user does tbot logs into the Lab PC
 173   line 12: accept_all: passed to paramiko, accept all connections
 174   line 13: keepalivetimout: passed to paramiko, timeout for sending
 175              keepalive message.
 176   line 14: channel_timeout: passed to paramiko
 177   line 15: loglevel: tbots loglevel for adding entries into the logfile.
 178   line 17: wdt_timeout: timeout in seconds for tbots watchdog.
 179              Watchdog gets triggered if prompt get read.
 180   line 24: tc_lab_denx_connect_to_board_tc: Which TC is used for
 181              connecting to the boards console the TC, here:
 182              https://github.com/hsdenx/tbot/blob/master/src/tc/tc_workfd_connect_with_kermit.py
 183   line 27: uboot_prompt: boards U-Boot prompt
 184   line 28: linux_prompt: boards linux prompt
 185
 186   Now comes a list of variables TC needs, this vary from which TC
 187   you start on the board.
 188
 189 Thats it ... you now can call tbot and hopefully, it works ;-)
 190 Find an example log [3] for calling simple U-Boot TC for setting
 191 an U-Boot Environmentvariable.
 192
 193 If you have problems in setting tbot up, please contact me
 194 (and may give me ssh access to your Lab PC ;-)
 195
 196 If you have running your first TC [3], you may want to write now your own
 197 TC (and hopefully share them), so continue with:
 198 u-boot:tools/tbot/README.create_a_new_testcase
 199
 200 Heiko Schocher <hs@denx.de>
 201 v2 2016.04.26
 202
 203 --------------
 204
 205 [1] tbot Dokumentation:
 206     [2] u-boot:/tools/tbot/README
 207     https://github.com/hsdenx/tbot/blob/master/README.md
 208     tbot-devel@googlegroups.com
 209
 210 [3] Example for a first U-Boot TC which should always work:
 211     (with commandline option "-v" for verbose output):
 212 hs@localhost:tbot  [event-devel] $ python2.7 src/common/tbot.py -c tbot_dxr2.cfg -t tc_ub_setenv.py -v -l log/tbot.log
 213 **** option cfg: tbot_dxr2.cfg log: log/tbot.log tc: tc_ub_setenv.py v 1
 214 ('CUR WORK PATH: ', '/home/hs/data/Entwicklung/tbot')
 215 ('CFGFILE ', 'tbot_dxr2.cfg')
 216 ('LOGFILE ', '/home/hs/data/Entwicklung/tbot/log/tbot.log')
 217 tb_ctrl: Last login: Mon Apr 25 14:52:42 2016 from 87.97.29.27
 218 *************************************************************
 219 BDI2000 Assignment:    (last updated:  2015-11-20 12:30 MET)
 220 bdi1  => techem     bdi2  => cetec_mx25   bdi3  => lpc3250
 221 bdi4  => -          bdi5  => --Rev.B!--   bdi6  => tqm5200s
 222 bdi7  => [stefano]  bdi8  => smartweb     bdi9  => sigmatek-nand
 223 bdi10 => pcm052     bdi11 => socrates     bdi12 => aristainetos
 224 bdi13 => imx53      bdi14 => ib8315       bdi15 => cairo
 225 bdi16 => g2c1       bdi17 => lwe090       bdi18 => symphony
 226 bdi19 => dxr2       bdi20 => ima3-mx6     bdi21 => sama5d3
 227 bdi98 => -          bdi99 => -            bdi0  => -
 228 Please power off unused systems when you leave!   Thanks, wd.
 229 *************************************************************
 230 tb_ctrl: pollux:~ hs $
 231 tb_ctrl: export PS1=ttbott
 232 ttbott
 233 tb_ctrl: stty cols 200
 234 ttbott
 235 tb_ctrl: export TERM=vt200
 236 ttbott
 237 tb_ctrl: echo $COLUMNS
 238 200
 239 ttbott
 240 tb_con: Last login: Tue Apr 26 06:28:59 2016 from 87.97.29.27
 241 *************************************************************
 242 BDI2000 Assignment:    (last updated:  2015-11-20 12:30 MET)
 243 bdi1  => techem     bdi2  => cetec_mx25   bdi3  => lpc3250
 244 bdi4  => -          bdi5  => --Rev.B!--   bdi6  => tqm5200s
 245 bdi7  => [stefano]  bdi8  => smartweb     bdi9  => sigmatek-nand
 246 bdi10 => pcm052     bdi11 => socrates     bdi12 => aristainetos
 247 bdi13 => imx53      bdi14 => ib8315       bdi15 => cairo
 248 bdi16 => g2c1       bdi17 => lwe090       bdi18 => symphony
 249 bdi19 => dxr2       bdi20 => ima3-mx6     bdi21 => sama5d3
 250 bdi98 => -          bdi99 => -            bdi0  => -
 251 Please power off unused systems when you leave!   Thanks, wd.
 252 *************************************************************
 253 tb_con: pollux:~ hs $
 254 tb_con: export PS1=ttbot
 255 tb_con: t
 256 ttbott
 257 tb_con: stty cols 200
 258 ttbott
 259 tb_con: export TERM=vt200
 260 ttbott
 261 tb_con: echo $COLUMNS
 262 200
 263 ttbott
 264 tb_con: ssh hs@lena
 265 tb_con: hs@lena's password:
 266 tb_con:
 267 tb_con: Last login: Mon Apr 25 07:03:29 2016 from 192.168.1.1
 268 tb_con: [hs@lena ~]$
 269 tb_con: export PS1=ttbott
 270 ttbott
 271 tb_con: stty cols 200
 272 ttbott
 273 tb_con: export TERM=vt200
 274 ttbott
 275 tb_con: echo $COLUMNS
 276 200
 277 ttbott
 278 tb_con: kermit
 279 C-Kermit 8.0.211, 10 Apr 2004, for Linux
 280  Copyright (C) 1985, 2004,
 281   Trustees of Columbia University in the City of New York.
 282 Type ? or HELP for help.
 283 (/home/hs/) C-Kermit>
 284 tb_con: set line /dev/ttyUSB0
 285 (/home/hs/) C-Kermit>
 286 tb_con: set speed 115200
 287 /dev/ttyUSB0, 115200 bps
 288 (/home/hs/) C-Kermit>
 289 tb_con: set flow-control none
 290 (/home/hs/) C-Kermit>
 291 tb_con: set carrier-watch off
 292 (/home/hs/) C-Kermit>
 293 tb_con: connect
 294 Connecting to /dev/ttyUSB0, speed 115200
 295  Escape character: Ctrl-\ (ASCII 28, FS): enabled
 296 Type the escape character followed by C to get back,
 297 or followed by ? to see other options.
 298 ----------------------------------------------------
 299 tb_con: <INTERRUPT>
 300 U-Boot#
 301 tb_con: U-Boot#
 302 U-Boot#
 303 tb_con: setenv Heiko Schocher
 304 U-Boot#
 305 tb_con: printenv Heiko
 306 Heiko=Schocher
 307 U-Boot#
 308 [('tc_workfd_ssh.py', 1, 0), ('tc_workfd_connect_with_kermit.py', 1, 0), ('tc_ub_setenv.py', 1, 0)]
 309 End of TBOT: success
 310 hs@localhost:tbot  [event-devel] $