`tbot.machine.board` Module¶

Warning

This is the documentation for an old version of tbot. Please head over to

https://tbot.tools/modules/machine_board.html

for the latest docs!

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.

property 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.

abstract property 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.

abstract poweron() → None[source]¶: Power on this board.

abstract 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.

property 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.

Create a new board machine.

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

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

property name¶: Name of this U-Boot machine.

destroy() → None[source]¶: Destroy this U-Boot machine.

build_command(*args: Union[str, tbot.machine.board.special.Special, tbot.machine.linux.path.Path[tbot.machine.linux.lab.machine.LabHost][tbot.machine.linux.lab.machine.LabHost]]) → 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: Union[str, tbot.machine.board.special.Special, tbot.machine.linux.path.Path[tbot.machine.linux.lab.machine.LabHost][tbot.machine.linux.lab.machine.LabHost]]) → 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: Union[str, tbot.machine.board.special.Special, tbot.machine.linux.path.Path[tbot.machine.linux.lab.machine.LabHost][tbot.machine.linux.lab.machine.LabHost]]) → 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: Union[str, tbot.machine.board.special.Special, tbot.machine.linux.path.Path[tbot.machine.linux.lab.machine.LabHost][tbot.machine.linux.lab.machine.LabHost]]) → 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: Union[str, tbot.machine.board.special.Special], 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.

Create a new instance of this LinuxMachine.

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")]

abstract property uboot¶: U-Boot machine for this board.

destroy() → None[source]¶: Destroy and cleanup this machine.

build_command(*args: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self]], 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: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self]], 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: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self]], 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

property 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.

property 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.

property lh¶: Return the lab-host of this board.

property name¶: Name of this linux machine.

abstract property password¶

Password for logging in.

Can be None to indicate that no password is needed.

abstract property shell¶: Shell that is in use on the board.

subshell(*args: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self]], 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: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self]], 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

abstract property username¶: Return the username for logging in on this machine.

property 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.

Create a new instance of this LinuxMachine.

build_command(*args: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self]], 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: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self]], 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: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self]], 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

property 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.

property 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.

property lh¶: Return the lab-host of this board.

property name¶: Name of this linux machine.

abstract property password¶

Password for logging in.

Can be None to indicate that no password is needed.

abstract property shell¶: Shell that is in use on the board.

subshell(*args: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self]], 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: Union[str, tbot.machine.linux.special.Special[~Self][Self], tbot.machine.linux.path.Path[~Self][Self]], 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

abstract property username¶: Return the username for logging in on this machine.

property workdir¶: Return a path where testcases can store data on this host.

destroy() → None[source]¶: Destroy and cleanup this machine.

tbot.machine.board Module¶

U-Boot¶

Special Characters¶

Linux¶

`tbot.machine.board` Module¶