Commandline¶
Overview¶
usage: there [-h] [-p PORT] [-b BAUDRATE] [--set-rtc]
[--reset-on-connect] [-c COMMAND] [-i] [--reset] [-u USER]
[-w PASSWORD] [-v] [--develop] [--timeit]
ACTION ...
Do stuff via the MicroPython REPL
optional arguments:
-h, --help show this help message and exit
port settings:
-p PORT, --port PORT set the serial port
-b BAUDRATE, --baudrate BAUDRATE
set the baud rate
operations before running action:
--set-rtc set the RTC to "now" before command is executed
--reset-on-connect do a soft reset as first operation (main.py will not
be executed)
operations after running action:
-c COMMAND, --command COMMAND
execute given code on target
-i, --interactive drop to interactive shell at the end
--reset do a soft reset on the end
login:
-u USER, --user USER response to login prompt
-w PASSWORD, --password PASSWORD
response to password prompt
diagnostics:
-v, --verbose show diagnostic messages, repeat for more
--develop show tracebacks on errors (development of this tool)
--timeit measure command run time
subcommands:
use "__main__.py ACTION --help" for more on each sub-command
ACTION sub-command help
detect help locating a board
run execute file contents on target
ls list files
hash hash files
cat print contents of one file
pull file(s) to copy from target
push file(s) to copy onto target
rm remove files from target
df Show filesystem information
mount Make target files accessible via FUSE
rtc Read the real time clock (RTC)
One or two --verbose
flag print progress information on stderr for some
actions, e.g. push
and pull
list deltas with one -v
and all files
with two. A third --verbose
(or -vvv
) also prints the data exchanged
between PC and target.
The order of operation is as follows:
- execute
--reset-on-connect
- execute action (
run
,push
etc.) - run statements that are given with
--command
- execute –reset
- start miniterm if
--interactive
is given
All of these steps can be combined or used on their own.
The environment variables MPY_PORT
, MPY_BAUDRATE
, MPY_USER
and
MPY_PASSWORD
are used as defaults if the corresponding command line options
are not given. And if those are not given, the default is hwgrep://USB
and
115200 baud, and None for user and password.
hwgrep://USB
picks a random USB-Serial adapter, works best if there
is only one MicroPython board connected. Otherwise the detect action should
be used to find the comport and use --port
option or environment
variable.
If --user
and --password
are given, it waits for a login and password
prompt after connecting. This is useful when connecting to e.g. a WiPy via
telnet.
Actions¶
detect
¶
Help finding MicroPython boards.
By default it simply lists all serial ports. If --test
is used, each of
the ports is opened (with the given --baudrate
) and tested for a Python
prompt. If there is no response it runs in a timeout, so this option is
quite a bit slower that just listing the ports.
usage: there detect [-h] [-t]
optional arguments:
-h, --help show this help message and exit
-t, --test open and test each port
run
¶
Execute the contents of a (small) file on the target, without saving it to the targets file system.
The file contents is sent to the REPL. The execution time is limited (see
--timeout
option to change) unless --interactive
is given, then
miniterm is started immediately.
usage: there run [-h] [-t TIMEOUT] [FILE]
positional arguments:
FILE load this file contents
optional arguments:
-h, --help show this help message and exit
-t TIMEOUT, --timeout TIMEOUT
wait x seconds for completion
Note, larger files can be executed using push
and --command
combined.
ls
¶
List files on the targets file system. With --long
more details are shown
such as the file size.
usage: there ls [-h] [-l] [-r] [PATH [PATH ...]]
positional arguments:
PATH paths to list
optional arguments:
-h, --help show this help message and exit
-l, --long show more info
-r, --recursive list contents of directories
The file date (shown in --long
format) is often not very useful as most
MicroPython boards do not have a battery backed RTC running.
cat
¶
Loads a file from the target and prints it contents to stdout (in binary mode).
usage: there cat [-h] PATH
positional arguments:
PATH filename on target
optional arguments:
-h, --help show this help message and exit
rm
¶
Remove files and/or directories on the target.
usage: there rm [-h] [-f] [-r] [--dry-run] PATH [PATH ...]
positional arguments:
PATH filename on target
optional arguments:
-h, --help show this help message and exit
-f, --force delete anyway / no error if not existing
-r, --recursive remove directories recursively
--dry-run do not actually create anything on target
pull
¶
Copies files and directories from the MicroPython board to the PC.
The remote path should be absolute (starting with /
) and supports
wildcards, e.g. /*.py
. On POSIX systems it may be needed to escape
wildcards to avoid local expansion (e.g. /\*.py
or with quotes
"/*.py"
.
usage: there pull [-h] [-r] [--dry-run] REMOTE [REMOTE ...] LOCAL
positional arguments:
REMOTE one or more source files/directories
LOCAL destination directory
optional arguments:
-h, --help show this help message and exit
-r, --recursive copy recursively
--dry-run do not actually create anything on target
push
¶
Copies files and directories from the PC to the MicroPython board.
The remote path should be absolute (starting with /
). When copying a single
file, the remote path may be a directory or a path including filename. When
copying multiple files it must be a directory. The local path supports
wildcards, e.g. *.py
.
usage: __main__.py push [-h] [-r] [--dry-run] [--force]
LOCAL [LOCAL ...] REMOTE
positional arguments:
LOCAL one or more source files/directories
REMOTE destination directory
optional arguments:
-h, --help show this help message and exit
-r, --recursive copy recursively
--dry-run do not actually create anything on target
--force write always, skip up-to-date check
Directories named .git
or __pycache__
are excluded.
By default files are first checked (SHA256) if they are already up to date
and copying is not needed. This speeds up transfer substantially. With
--force
, this check will be skipped and the files are always transferred.
The action can also be combined with --command
and
--interactive
to start the downloaded code and see its
output.
mkdir
¶
Create new directory.
usage: there mkdir [-h] [--parents] PATH [PATH ...]
positional arguments:
PATH filename on target
optional arguments:
-h, --help show this help message and exit
--parents create parents
hash
¶
Generate and print a SHA256 hash for each file given.
usage: there hash [-h] [-r] [PATH [PATH ...]]
positional arguments:
PATH paths to list
optional arguments:
-h, --help show this help message and exit
-r, --recursive list contents of directories
df
¶
Show file system info.
usage: theredf [-h] [PATH [PATH ...]]
positional arguments:
PATH remote path
optional arguments:
-h, --help show this help message and exit
mount
¶
Mount the target as file system via FUSE.
usage: there mount [-h] [-e] MOUNTPOINT
positional arguments:
MOUNTPOINT local mount point, directory must exist
optional arguments:
-h, --help show this help message and exit
-e, --explore auto open file explorer at mount point
A virtual file system is created and attached to the given directory. It mirrors the contents of the MicroPython board. Operations such as creating, renaming, deleting are supported.
To improve performance, the mount command is caching data such as directory listings and stat file infos. The cache is set to be valid for 10 seconds.
rtc
¶
Read and print the real time clock on baords that support pyb.RTC()
:
usage: __main__.py rtc [-h] [--test]
optional arguments:
-h, --help show this help message and exit
--test test if the clock runs
The --test
function reads the clock twice and check that it is running.