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       As this TC powers on the board for all your boards in your VL,
  97       you can differ between the boards through the tbot class
  98       variable "tb.boardlabname" (which is in the default case the
  99       same as "tb.boardname"), but you may need to name the power target
 100       with an other name than boardname, so you can configure this case.
 101
 102       If connect fails end this TC with "tb.end_tc(False)"
 103       else call "tb.end_tc(True)"
 104
 105       If you want to use kermit for connecting to the boards console, you
 106       can use:
 107
 108       https://github.com/hsdenx/tbot/blob/master/src/tc/tc_workfd_connect_with_kermit.py
 109
 110       Example for such a board in the VL from denx:
 111       self.tc_lab_denx_connect_to_board_tc = 'tc_workfd_connect_with_kermit.py'
 112       https://github.com/hsdenx/tbot/blob/master/tbot_dxr2.cfg#L24
 113
 114       Hopefully this works for you too.
 115
 116     - set in your board config file:
 117       self.tc_lab_denx_connect_to_board_tc = 'tc_lab_denx_connect_to_board_XXX.py'
 118
 119   remarks while writting this:
 120   - Currently there is only the denx VL. Original idea was to include
 121     other VL through a seperate class/file in
 122     https://github.com/hsdenx/tbot/tree/master/src/lab_api
 123     but it turned out, that if we say "ssh" is the standard way to connect
 124     to a VL, we can integrate the VL specific tasks through testcases, see
 125     above, so we should do:
 126     - rename the "denx" API to a more general name.
 127       This is a point on my ToDo list ... done, renamed to 'ssh_std'
 128
 129   - the VL specific configuration may moved from the board config files
 130     and should be collected in VL specific config files, which boards
 131     config file simple include.
 132
 133 - prepare password.py file:
 134   This file contains all passwords tbot needs (for example for
 135   linux login on the boards)
 136   tbot searches this file in the tbot root directory.
 137   It is a simple python file, for example:
 138
 139   # passwords for the lab
 140   if (board == 'lab'):
 141       if (user == 'hs'):
 142           password = 'passwordforuserhs'
 143       if (user == 'root'):
 144           password = 'passwordforrootuser'
 145   # passwords for the boards
 146   elif (board == 'mcx'):
 147       if (user == 'root'):
 148           password = 'passwordformcxrootfs'
 149   else:
 150       if (user == 'root'):
 151           password = ''
 152
 153   In the above example passwords for logging into the Lab PC tbot finds
 154   through:
 155   if (board == 'lab'):
 156      user = 'name':
 157          password = 'gnlmpf' # password 'gnlmpf' for login of user 'name'
 158
 159 - prepare board config file
 160   Each board which is found in the VL needs a tbot configuration file
 161   pass the config file name with the option '-c' to tbot, tbot searches
 162   in the root dir for them.
 163
 164   board Example (dxr2 board):
 165   https://github.com/hsdenx/tbot/blob/master/tbot_dxr2.cfg
 166
 167   Necessary variables:
 168
 169   line  3: boardname, here it is the "etamin" board
 170              no default value, must be set.
 171   line  4: boardlabname: name used for connecting to the board
 172              may differ from tb.boardname, default tb.boardname
 173   line  5: boardlabpowername: name used for power on/off
 174              may differ from tb.boardname, default tb.boardname
 175   line  6: tftpboardname: name used for tftp subdir (from where
 176              U-Boot loads images for example).
 177              may differ from tb.boardname, default tb.boardname
 178   line  7: labprompt: linux prompt tbot sets
 179              no defaultvalue, must be set (maybe we should introduce
 180              "ttbott" as default ...
 181   line  8: debug: If True, adds debug output on the tbot shell
 182   line  9: debugstatus: enable status debug output on the shell
 183   line 10: ip: Where tbot finds the Lab PC
 184   line 11: user: As which user does tbot logs into the Lab PC
 185   line 12: accept_all: passed to paramiko, accept all connections
 186   line 13: keepalivetimout: passed to paramiko, timeout for sending
 187              keepalive message.
 188   line 14: channel_timeout: passed to paramiko
 189   line 15: loglevel: tbots loglevel for adding entries into the logfile.
 190   line 16: lap_api: used lap API (currently only 'ssh_std')
 191              Should be declared as standard -> this line would be not needed
 192              longer.
 193   line 17: wdt_timeout: timeout in seconds for tbots watchdog.
 194              Watchdog gets triggered if prompt get read.
 195   line 20,21: include 'ssh_std' api
 196              should be removed.
 197   line 24: tc_lab_denx_connect_to_board_tc: Which TC is used for
 198              connecting to the boards console the TC, here:
 199              https://github.com/hsdenx/tbot/blob/master/src/tc/tc_workfd_connect_with_kermit.py
 200   line 27: uboot_prompt: boards U-Boot prompt
 201   line 28: linux_prompt: boards linux prompt
 202
 203   Now comes a list of variables TC needs, this vary from which TC
 204   you start on the board.
 205
 206 Thats it ... you now can call tbot and hopefully, it works ;-)
 207 Find an example log [3] for calling simple U-Boot TC for setting
 208 an U-Boot Environmentvariable.
 209
 210 If you have problems in setting tbot up, please contact me
 211 (and may give me ssh access to your Lab PC ;-)
 212
 213 If you have running your first TC [3], you may want to write now your own
 214 TC (and hopefully share them), so continue with:
 215 u-boot:tools/tbot/README.create_a_new_testcase
 216
 217 Heiko Schocher <hs@denx.de>
 218 v1 2016.01.22
 219
 220 --------------
 221
 222 [1] tbot Dokumentation:
 223     [2] u-boot:/tools/tbot/README
 224     https://github.com/hsdenx/tbot/blob/master/README.md
 225
 226 [3] Example for a first U-Boot TC which should always work:
 227     (with commandline option "-v" for verbose output):
 228
 229 hs@localhost:tbot  [master] $ python2.7 src/common/tbot.py -c tbot_dxr2.cfg -t tc_ub_setenv.py -v -l log/tbot.log
 230 **** option cfg: tbot_dxr2.cfg log: log/tbot.log tc: tc_ub_setenv.py v 1
 231 ('CUR WORK PATH: ', '/home/hs/data/Entwicklung/tbot')
 232 ('CFGFILE ', 'tbot_dxr2.cfg')
 233 ('LOGFILE ', '/home/hs/data/Entwicklung/tbot/log/tbot.log')
 234 (<denx.tbot_lab_api object at 0x7f53ac1808d0>, <tbotlib.tbot object at 0x7f53a45fd410>, True)
 235 (<denx.tbot_lab_api object at 0x7f53ac1808d0>, <tbotlib.tbot object at 0x7f53a45fd410>, True)
 236 read 0: Last login: Fri Jan 22 12:20:12 2016 from 87.97.28.177
 237 read 0:
 238 read 0: *************************************************************
 239 read 0: BDI2000 Assignment:    (last updated:  2015-11-20 12:30 MET)
 240 read 0: bdi1  => techem     bdi2  => cetec_mx25   bdi3  => lpc3250
 241 read 0: bdi4  => -          bdi5  => --Rev.B!--   bdi6  => tqm5200s
 242 read 0: bdi7  => [stefano]  bdi8  => smartweb     bdi9  => sigmatek-nand
 243 read 0: bdi10 => pcm052     bdi11 => socrates     bdi12 => aristainetos
 244 read 0: bdi13 => imx53      bdi14 => ib8315       bdi15 => cairo
 245 read 0: bdi16 => g2c1       bdi17 => lwe090       bdi18 => symphony
 246 read 0: bdi19 => dxr2       bdi20 => ima3-mx6     bdi21 => sama5d3
 247 read 0: bdi98 => -          bdi99 => -            bdi0  => -
 248 read 0: Please power off unused systems when you leave!   Thanks, wd.
 249 read 0: *************************************************************
 250 read no ret 0:
 251 pollux:~ hs $
 252 write 0: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
 253 read 0: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
 254 read 0: hs@pollux [12:21:00] ttbott >
 255 read 1: Last login: Fri Jan 22 12:20:59 2016 from 87.97.28.177
 256 read 1:
 257 read 1: *************************************************************
 258 read 1: BDI2000 Assignment:    (last updated:  2015-11-20 12:30 MET)
 259 read 1: bdi1  => techem     bdi2  => cetec_mx25   bdi3  => lpc3250
 260 read 1: bdi4  => -          bdi5  => --Rev.B!--   bdi6  => tqm5200s
 261 read 1: bdi7  => [stefano]  bdi8  => smartweb     bdi9  => sigmatek-nand
 262 read 1: bdi10 => pcm052     bdi11 => socrates     bdi12 => aristainetos
 263 read 1: bdi13 => imx53      bdi14 => ib8315       bdi15 => cairo
 264 read 1: bdi16 => g2c1       bdi17 => lwe090       bdi18 => symphony
 265 read 1: bdi19 => dxr2       bdi20 => ima3-mx6     bdi21 => sama5d3
 266 read 1: bdi98 => -          bdi99 => -            bdi0  => -
 267 read 1: Please power off unused systems when you leave!   Thanks, wd.
 268 read 1: *************************************************************
 269 read no ret 1:
 270 pollux:~ hs $
 271 write 1: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
 272 read 1: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
 273 read 1: hs@pollux [12:21:02] ttbott >
 274 write 0: remote_power dxr2 -l
 275 read 0: hs@pollux [12:21:00] ttbott >remote_power dxr2 -l
 276 read 0: dxr2            ON
 277 read 0: hs@pollux [12:21:02] ttbott >
 278 read no ret 1:
 279 hs@pollux [12:21:02] ttbott >
 280 write 1: ssh hs@lena
 281 read 1: ssh hs@lena
 282 read no ret 1:
 283 hs@lena's password:
 284 read 1:
 285 read 1: Last login: Fri Jan 22 12:20:17 2016 from 192.168.1.1
 286 read 1:
 287 read no ret 1:
 288 [hs@lena ~]$
 289 write 1: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
 290 read 1: export PS1="\u@\h [\$(date +%k:%M:%S)] ttbott >"
 291 read 1: hs@lena [12:21:07] ttbott >
 292 read no ret 1:
 293 hs@lena [12:21:07] ttbott >
 294 write 1: stty cols 200
 295 read 1: stty cols 200
 296 read 1: hs@lena [12:21:08] ttbott >
 297 write 1: export TERM=vt200
 298 read 1: hs@lena [12:21:08] ttbott >export TERM=vt200
 299 read 1: hs@lena [12:21:08] ttbott >
 300 write 1: echo $COLUMNS
 301 read 1: hs@lena [12:21:08] ttbott >echo $COLUMNS
 302 read 1: 200
 303 read 1: hs@lena [12:21:08] ttbott >
 304 write 1: kermit
 305 read 1: hs@lena [12:21:08] ttbott >kermit
 306 read 1: C-Kermit 8.0.211, 10 Apr 2004, for Linux
 307 read 1:
 308 read 1:  Copyright (C) 1985, 2004,
 309 read 1:   Trustees of Columbia University in the City of New York.
 310 read 1: Type ? or HELP for help.
 311 read 1:
 312 read 1: (/home/hs/) C-Kermit>
 313 read 1:
 314 read no ret 1: (/home/hs/) C-Kermit>
 315 write 1: set line /dev/ttyUSB0
 316 read 1: set line /dev/ttyUSB0
 317 read 1:
 318 read 1: (/home/hs/) C-Kermit>
 319 write 1: set speed 115200
 320 read 1:
 321 read 1: (/home/hs/) C-Kermit>set speed 115200
 322 read 1: /dev/ttyUSB0, 115200 bps
 323 read 1:
 324 read 1: (/home/hs/) C-Kermit>
 325 write 1: set flow-control none
 326 read 1:
 327 read 1: (/home/hs/) C-Kermit>set flow-control none
 328 read 1:
 329 read 1: (/home/hs/) C-Kermit>
 330 write 1: set carrier-watch off
 331 read 1:
 332 read 1: (/home/hs/) C-Kermit>set carrier-watch off
 333 read 1:
 334 read 1: (/home/hs/) C-Kermit>
 335 write 1: connect
 336 read 1:
 337 read 1: (/home/hs/) C-Kermit>connect
 338 read 1: Connecting to /dev/ttyUSB0, speed 115200
 339 read 1:
 340 read 1:  Escape character: Ctrl-\ (ASCII 28, FS): enabled
 341 read 1:
 342 read 1: Type the escape character followed by C to get back,
 343 read 1:
 344 read 1: or followed by ? to see other options.
 345 read 1:
 346 read 1: ----------------------------------------------------
 347 read no ret 1:
 348
 349 write no ret 1:
 350
 351 read 1:
 352 read 1: Heiko=Schocher
 353 read no ret 1:
 354 U-Boot#
 355 write no ret 1:
 356 write no ret 1:
 357
 358 read 1: <INTERRUPT>
 359 read 1: U-Boot#
 360 write 1: setenv Heiko Schocher
 361 read 1: U-Boot# setenv Heiko Schocher
 362 read no ret 1:
 363 U-Boot#
 364 write 1: printenv Heiko
 365 read 1: printenv Heiko
 366 read 1: Heiko=Schocher
 367 read no ret 1:
 368 U-Boot#
 369 End of TBOT: success
 370 hs@localhost:tbot  [master] $