tbot.machine.board Module

class tbot.machine.board.Board(lh: tbot.machine.linux.lab.machine.LabHost)[source]

Bases: contextlib.AbstractContextManager

Abstract base class for boards.

Implementation example:

from tbot.machine import board
from tbot.machine import channel
from tbot.machine import linux

class MyBoard(board.Board):
    name = "my-board"

    def poweron(self) -> None:
        # Command to power on the board
        self.lh.exec0("poweron", self.name)

    def poweroff(self) -> None:
        # Command to power off the board
        self.lh.exec0("poweroff", self.name)

    def connect(self) -> channel.Channel:
        return self.lh.new_channel(
            "picocom",
            "-b",
            "115200",
            linux.Path(self.lh, "/dev") / f"tty-{self.name}",
        )

Initialize an instance of this board.

This will not yet power on the board. For that you need to use a with block:

with MyBoard(lh) as b:
    ...
Parameters:lh (tbot.machine.linux.LabHost) – LabHost from where to connect to the Board.
connect_wait

Time to wait after connecting before powering on (float).

This is supposed to allow telnet/rlogin/whatever to take some time to establish the connection.

name

Name of this board.

console_check() → None[source]

Run this check before actually interacting with the board.

This hook allows you to ensure the console is unoccupied so you don’t accidentally interfere with other developers.

Return if the console if ok, raise an Exception if it is not.

Note

If the connect command fails in less than connect_wait seconds, this check is not needed. It is, however, definitely the safer way.

poweron() → None[source]

Power on this board.

poweroff() → None[source]

Power off this board.

connect() → Optional[tbot.machine.channel.channel.Channel][source]

Connect to the serial port of this board.

cleanup() → None[source]

Cleanup the connection.

Might be necessary if the tbot’s default behaviour of just killing the shell leaves lock files behind.

class tbot.machine.board.BoardMachine(board: B)[source]

Bases: tbot.machine.machine.Machine, typing.Generic

Abstract base for board machines.

Create a new board machine.

Parameters:board (tbot.machine.board.Board) – The board this machine should use.
lh

Return the lab-host of this board.

U-Boot

class tbot.machine.board.UBootMachine(board: B)[source]

Bases: tbot.machine.board.machine.BoardMachine, tbot.machine.machine.InteractiveMachine

Generic U-Boot board machine.

Example implementation:

from tbot.machine import board

class MyBoard(board.Board):
    ...

class MyBoardUBoot(board.UBootMachine[MyBoard]):
    prompt = "=> "

BOARD = MyBoard
UBOOT = MyBoardUBoot
Variables:bootlog (str) –

Messages that were printed out during startup. You can access this attribute inside your testcases to get info about what was going on during boot.

New in version 0.6.2.

autoboot_prompt = 'Hit any key to stop autoboot:\\s+\\d+\\s+'

Regular expression of the autoboot prompt. Set this to None if autoboot is disabled for this board.

autoboot_keys = '\n'

Keys that should be sent to intercept autoboot

prompt = 'U-Boot> '

U-Prompt that was configured when building U-Boot

name

Name of this U-Boot machine.

destroy() → None[source]

Destroy this U-Boot machine.

build_command(*args) → str[source]

Return the string representation of a command.

Parameters:args – Each argument can either be a str or a special token like Env.
Return type:str
exec(*args) → Tuple[int, str][source]

Run a command in U-Boot and check its return value.

Parameters:args – Each argument can either be a str or a special token like Env.
Return type:tuple[int, str]
Returns:A tuple with the return code and output of the command
exec0(*args) → str[source]

Run a command in U-Boot and ensure its return value is zero.

Parameters:args – Each argument can either be a str or a special token like Env.
Return type:str
Returns:The output of the command
test(*args) → bool[source]

Run a command and test if it succeeds.

Parameters:args – Each argument can either be a str or a special token like Env.
Return type:bool
Returns:True if the return code is 0, else False.
env(var: str, value: Union[str, tbot.machine.board.special.Special, None] = None) → str[source]

Get or set the value of an environment variable.

Parameters:
  • var (str) – The variable’s name
  • value (str) – The value the var should be set to. If this parameter is given, env will set, else it will just read a variable
Return type:

str

Returns:

Value of the environment variable

New in version 0.6.2.

Changed in version 0.6.5: You can use env() to set environment variables as well.

Changed in version 0.6.6: The value can now be any tbot.machine.board.special

interactive() → None[source]

Drop into an interactive U-Boot session.

Raises:RuntimeError – If tbot was not able to reacquire the shell after the session is over.

Special Characters

class tbot.machine.board.Env(name: str)[source]

Bases: tbot.machine.board.special.Special

U-Boot environment variable.

Expand the name env variable.

resolve_string() → str[source]

Return the string representation of this special char.

class tbot.machine.board.F(fmt: str, *args, quote: bool = True)[source]

Bases: tbot.machine.board.special.Special

Format string.

Create a format string.

Example:

m.exec0("setenv", "foo", board.F("0x{}", board.Env("loadaddr"), quote=False))

All normal python formatters are supported.

Parameters:
  • fmt (str) – Format string
  • args – Format arguments.
  • quote (bool) – Whether to escape the resulting string.
resolve_string() → str[source]

Return the string representation of this special character.

class tbot.machine.board.Raw(text: str)[source]

Bases: tbot.machine.board.special.Special

Raw string.

Create a new raw unescaped string text.

resolve_string() → str[source]

Return the string representation of this special char.

tbot.machine.board.Then

Special character for the ; separator to run multiple commands

Example:

m.exec0("if", "true", board.Then, "then", "echo", "Hallo", board.Then, "fi")

Linux

class tbot.machine.board.LinuxWithUBootMachine(b: Union[B, tbot.machine.board.uboot.UBootMachine[~B][B]])[source]

Bases: tbot.machine.board.linux.LinuxMachine

Linux machine that boots from U-Boot.

Example Implementation:

from tbot.machine import board

class MyBoard(board.Board):
    ...

class MyBoardUBoot(board.UBootMachine[MyBoard]):
    ...

class MyBoardLinux(board.LinuxWithUBootMachine[MyBoard]):
    uboot = MyBoardUBoot

    username = "root"
    password = None

    boot_commands = [
        ["tftp", board.Env("loadaddr"), "zImage"],
        ["bootz", board.Env("loadaddr")],
    ]

BOARD = MyBoard
UBOOT = MyBoardUBoot
LINUX = MyBoardLinux
Variables:bootlog (str) –

Messages that were printed out during startup. You can access this attribute inside your testcases to get info about what was going on during boot.

New in version 0.6.2.

boot_commands = None

List of commands to boot Linux from U-Boot. Commands are a list, of the arguments that are given to exec0()

By default, do_boot is called, but if boot_commands is defined, it will be used instead (and do_boot is ignored).

Example:

boot_commands = [
    ["setenv", "console", "ttyS0"],
    ["setenv", "baudrate", str(115200)],
    [
        "setenv",
        "bootargs",
        board.Raw("console=${console},${baudrate}"),
    ],
    ["tftp", board.Env("loadaddr"), "zImage"],
    ["bootz", board.Env("loadaddr")],
]
do_boot(ub: tbot.machine.board.uboot.UBootMachine[~B][B]) → List[Union[str, tbot.machine.board.special.Special]][source]

Run commands to boot linux on ub.

The last command, the one that actually kicks off the boot process, needs to be returned as a list of arguments.

do_boot will only be called, if boot_commands is None.

Example:

def do_boot(
    self, ub: board.UBootMachine[B]
) -> typing.List[typing.Union[str, board.Special]]:
    ub.exec0("setenv", "console", "ttyS0")
    ub.exec0("setenv", "baudrate", str(115200))
    ub.exec0(
        "setenv",
        "bootargs",
        board.Raw("console=${console},${baudrate}"),
    )
    ub.exec0("tftp", board.Env("loadaddr"), "zImage")

    return ["bootz", board.Env("loadaddr")]
uboot

U-Boot machine for this board.

destroy() → None[source]

Destroy and cleanup this machine.

build_command(*args, stdout: Optional[tbot.machine.linux.path.Path[~Self][Self]] = None) → str

Build the string representation of a command.

Parameters:
  • args – Each arg is a token that will be sent to the shell. Can be either a str, a Special or a Path that is associated with this host. Arguments will be escaped (a str like “a b” will not result in separate arguments to the command)
  • stdout (Path) – File where stdout should be directed to
Returns:

A string that would be sent to the machine to execute the command

Return type:

str

env(var: str, value: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self], None] = None) → str

Get or set the value of an environment variable.

Parameters:
  • var (str) – The variable’s name
  • value (str) – The value the var should be set to. If this parameter is given, env will set, else it will just read a variable
Return type:

str

Returns:

Value of the environment variable

New in version 0.6.2.

Changed in version 0.6.5: You can use env() to set environment variables as well.

exec(*args, stdout: Optional[tbot.machine.linux.path.Path[~Self][Self]] = None, timeout: Optional[float] = None) → Tuple[int, str]

Run a command on this machine.

Parameters:
  • args – Each arg is a token that will be sent to the shell. Can be either a str, a Special or a Path that is associated with this host. Arguments will be escaped (a str like “a b” will not result in separate arguments to the command)
  • stdout (Path) – File where stdout should be directed to
Returns:

Tuple with the exit code and a string containing the combined stdout and stderr of the command (with a trailing newline).

Return type:

(int, str)

exec0(*args, stdout: Optional[tbot.machine.linux.path.Path[~Self][Self]] = None, timeout: Optional[float] = None) → str

Run a command on this machine and ensure it succeeds.

Parameters:
  • args – Each arg is a token that will be sent to the shell. Can be either a str, a Special or a Path that is associated with this host. Arguments will be escaped (a str like “a b” will not result in separate arguments to the command)
  • stdout (Path) – File where stdout should be directed to
Returns:

A string containing the combined stdout and stderr of the command (with a trailing newline).

Return type:

str

fsroot

Return a path to the filesystem root.

This is a helper to allow the following:

vers = lh.fsroot / "proc" / "version"

New in version 0.6.6.

home

Return a path to the current user’s home directory.

Example:

bashrc = h.exec0("cat", h.home / ".bashrc").strip()
interactive() → None

Drop into an interactive session on this machine.

lh

Return the lab-host of this board.

name

Name of this linux machine.

password

Password for logging in.

Can be None to indicate that no password is needed.

shell

Shell that is in use on the board.

subshell(*args, shell: Optional[Type[tbot.machine.linux.shell.shell.Shell]] = None) → tbot.machine.linux.machine._SubshellContext

Start a subshell for isolating environment changes.

If no arguments are supplied, the shell defined for this machine is used. If arguments are given, they are expected to open a shell of type shell which defaults to the shell specified for this machine.

Example:

with tbot.acquire_lab() as lh:
    lh.exec0("echo", linux.Env("FOOVAR"))  # Empty result

    with lh.subshell():
        lh.env("FOOVAR", "123")
        lh.exec0("echo", linux.Env("FOOVAR"))  # 123

    lh.exec0("echo", linux.Env("FOOVAR"))  # Empty result
Parameters:shell (Shell) – Shell that is started

New in version 0.6.1.

test(*args, stdout: Optional[tbot.machine.linux.path.Path[~Self][Self]] = None, timeout: Optional[float] = None) → bool

Run a command and test if it succeeds.

Parameters:
  • args – Each arg is a token that will be sent to the shell. Can be either a str, a Special or a Path that is associated with this host. Arguments will be escaped (a str like “a b” will not result in separate arguments to the command)
  • stdout (Path) – File where stdout should be directed to
Returns:

True if the return code is 0, else False.

Return type:

bool

username

Return the username for logging in on this machine.

workdir

Return a path where testcases can store data on this host.

class tbot.machine.board.LinuxStandaloneMachine(b: Union[B, tbot.machine.board.uboot.UBootMachine[~B][B]])[source]

Bases: tbot.machine.board.linux.LinuxMachine

Linux machine that boots without U-Boot.

Example Implementation:

from tbot.machine import board
from tbot.machine import linux

class MyBoard(board.Board):
    ...

class MyBoardLinux(board.LinuxStandaloneMachine[MyBoard]):
    username = "root"
    password = None
    shell = linux.shell.Bash


BOARD = MyBoard
LINUX = MyBoardLinux
Variables:bootlog (str) –

Messages that were printed out during startup. You can access this attribute inside your testcases to get info about what was going on during boot.

New in version 0.6.2.

build_command(*args, stdout: Optional[tbot.machine.linux.path.Path[~Self][Self]] = None) → str

Build the string representation of a command.

Parameters:
  • args – Each arg is a token that will be sent to the shell. Can be either a str, a Special or a Path that is associated with this host. Arguments will be escaped (a str like “a b” will not result in separate arguments to the command)
  • stdout (Path) – File where stdout should be directed to
Returns:

A string that would be sent to the machine to execute the command

Return type:

str

env(var: str, value: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self], None] = None) → str

Get or set the value of an environment variable.

Parameters:
  • var (str) – The variable’s name
  • value (str) – The value the var should be set to. If this parameter is given, env will set, else it will just read a variable
Return type:

str

Returns:

Value of the environment variable

New in version 0.6.2.

Changed in version 0.6.5: You can use env() to set environment variables as well.

exec(*args, stdout: Optional[tbot.machine.linux.path.Path[~Self][Self]] = None, timeout: Optional[float] = None) → Tuple[int, str]

Run a command on this machine.

Parameters:
  • args – Each arg is a token that will be sent to the shell. Can be either a str, a Special or a Path that is associated with this host. Arguments will be escaped (a str like “a b” will not result in separate arguments to the command)
  • stdout (Path) – File where stdout should be directed to
Returns:

Tuple with the exit code and a string containing the combined stdout and stderr of the command (with a trailing newline).

Return type:

(int, str)

exec0(*args, stdout: Optional[tbot.machine.linux.path.Path[~Self][Self]] = None, timeout: Optional[float] = None) → str

Run a command on this machine and ensure it succeeds.

Parameters:
  • args – Each arg is a token that will be sent to the shell. Can be either a str, a Special or a Path that is associated with this host. Arguments will be escaped (a str like “a b” will not result in separate arguments to the command)
  • stdout (Path) – File where stdout should be directed to
Returns:

A string containing the combined stdout and stderr of the command (with a trailing newline).

Return type:

str

fsroot

Return a path to the filesystem root.

This is a helper to allow the following:

vers = lh.fsroot / "proc" / "version"

New in version 0.6.6.

home

Return a path to the current user’s home directory.

Example:

bashrc = h.exec0("cat", h.home / ".bashrc").strip()
interactive() → None

Drop into an interactive session on this machine.

lh

Return the lab-host of this board.

name

Name of this linux machine.

password

Password for logging in.

Can be None to indicate that no password is needed.

shell

Shell that is in use on the board.

subshell(*args, shell: Optional[Type[tbot.machine.linux.shell.shell.Shell]] = None) → tbot.machine.linux.machine._SubshellContext

Start a subshell for isolating environment changes.

If no arguments are supplied, the shell defined for this machine is used. If arguments are given, they are expected to open a shell of type shell which defaults to the shell specified for this machine.

Example:

with tbot.acquire_lab() as lh:
    lh.exec0("echo", linux.Env("FOOVAR"))  # Empty result

    with lh.subshell():
        lh.env("FOOVAR", "123")
        lh.exec0("echo", linux.Env("FOOVAR"))  # 123

    lh.exec0("echo", linux.Env("FOOVAR"))  # Empty result
Parameters:shell (Shell) – Shell that is started

New in version 0.6.1.

test(*args, stdout: Optional[tbot.machine.linux.path.Path[~Self][Self]] = None, timeout: Optional[float] = None) → bool

Run a command and test if it succeeds.

Parameters:
  • args – Each arg is a token that will be sent to the shell. Can be either a str, a Special or a Path that is associated with this host. Arguments will be escaped (a str like “a b” will not result in separate arguments to the command)
  • stdout (Path) – File where stdout should be directed to
Returns:

True if the return code is 0, else False.

Return type:

bool

username

Return the username for logging in on this machine.

workdir

Return a path where testcases can store data on this host.

destroy() → None[source]

Destroy and cleanup this machine.