tools/mpremote: Add `delay` and `rtc` commands. Extend documentation. #11659

jimmo · 2023-05-30T07:37:41Z

Minor mpremote updates:

Add delay command allowing a pause between commands.
Replace the setrtc "shortcut" command with a new rtc [--set] command which allows getting/setting the RTC (to the current local time).
Add a backwards compatible shortcut for setrtc.
Fix argument handling for shortcuts (to allow terminator).
Handle cp with no destination.

Extensive documentation update for mpremote:

Add a extra detail to each of the commands.
Add more about handling options and arguments.
Include shortcut commands that behave like real commands to the
command list (e.g. bootloader, rtc).
Add extra information and reword to address common misconceptions, in
particular how commands chain together.
Add additional examples showing some more interesting combinations.
Add descriptions to each of the examples.
Add pipx installation instructions.
Describe how user-configuration works.

This work was funded in combination through GitHub Sponsors and Google Season of Docs.

github-actions · 2023-05-30T07:44:08Z

Code size report:

   bare-arm:    +0 +0.000% 
minimal x86:    +0 +0.000% 
   unix x64:    +0 +0.000% standard
      stm32:    +0 +0.000% PYBV10
        rp2:    +0 +0.000% PICO

codecov · 2023-05-30T07:54:23Z

Codecov Report

Merging #11659 (f59f4d5) into master (e4886dd) will decrease coverage by 0.02%.
The diff coverage is n/a.

❗ Current head f59f4d5 differs from pull request most recent head bd5d016. Consider uploading reports for the commit bd5d016 to get more accurate results

@@            Coverage Diff             @@
##           master   #11659      +/-   ##
==========================================
- Coverage   98.40%   98.39%   -0.02%     
==========================================
  Files         156      156              
  Lines       20609    20614       +5     
==========================================
+ Hits        20281    20283       +2     
- Misses        328      331       +3

see 7 files with indirect coverage changes

Wind-stormger · 2023-05-30T08:19:25Z

delay seems to allow most ESP32 boards using USB-CDC to reconnect and perform subsequent actions after a hardware reset.

mattytrentini

A great improvement to the mpremote docs!

docs/reference/mpremote.rst

mattytrentini · 2023-05-30T13:49:53Z

docs/reference/mpremote.rst


  .. code-block:: bash

-      $ mpremote fs <command>
+      $ mpremote fs <sub-command>


Many people I've shown mpremote to are confused by fs. "Why bother using it when all the sub-commands are commands anyway"? Explaining that they are implemented as shortcuts doesn't help...I'm not sure what the solution is here, just sharing the feedback!

I am confused by this too :p

I've added a Note: to this section, to at least acknowledge that this is a thing and not some extra magic.

mattytrentini · 2023-05-30T13:53:11Z

docs/reference/mpremote.rst

+
+.. code-block:: bash
+
+    $ pipx run mpremote


I'd prefer to see pipx install mpremote as the example - make it easy for beginners to just copy 'n' paste. run is handy but less useful.

I'd also be sorely tempted to place pipx ahead of pip; it's just a better way to install the tool. But I get that pip is more...standard.

I've updated it, see what you think.

mattytrentini · 2023-05-30T13:58:32Z

docs/reference/mpremote.rst

-      $ mpremote run <file>
+      $ mpremote run <file.py>
+
+  This will copy the file to RAM on the device and execute it directly.


Perhaps with less ambiguity:

Suggested change

This will copy the file to RAM on the device and execute it directly.

Transfer <file.py> to the device where it will be compiled and executed.

(Mainly because it sounded like it was copied to a RAM disk.)

I'm not sure about the suggested wording because to me "transfer to the device" implies copying it to the filesystem. I've updated the wording to not say "copy". (And sentence about what this command is useful for).

docs/reference/mpremote.rst

mattytrentini · 2023-05-30T14:11:14Z

docs/reference/mpremote.rst

- mount the local directory on the remote device:
+.. _mpremote_command_mount:
+
+- **mount** -- mount the local directory on the remote device:

  .. code-block:: bash

      $ mpremote mount [options] <local-dir>


This is a good improvement - for a very difficult topic to explain!

I wonder if this should have a short animated gif? To show a simple sequence like:

ls device - empty

ls PC - foo.py

mount, ls device - foo.py

Or maybe we just need to record a video, as we've discussed.

Yep. +1 to video.

mattytrentini · 2023-05-30T14:15:50Z

docs/reference/mpremote.rst

-Shortcuts can be defined using the macro system.  Built-in shortcuts are::
+Shortcuts can be defined using the macro system.  Built-in shortcuts are:
+
+- ``devs``: Alias for ``connect list``


FWIW, I'm often asked how devs filters the serial device list to detect MicroPython devices.

devs (i.e.connect list) doesn't filter, but auto does, so I have explained that.

docs/reference/mpremote.rst

jimmo · 2023-05-31T01:08:23Z

Thanks @mattytrentini -- updated the branch.

dpgeorge · 2023-06-02T03:55:21Z

tools/mpremote/mpremote/main.py

@@ -212,6 +222,10 @@ def argparse_none(description):
        do_connect,
        argparse_connect,
    ),
+    "delay": (


maybe this should be delay_ms to be clear on the units (and match sleep_ms)?

I went with millis to match the existing args to reset/bootloader, but the new sleep command kind of makes those arguments unnecessary, so removed them instead. sleep now uses seconds (to match unix sleep(1)).

dpgeorge · 2023-06-02T03:57:15Z

tools/mpremote/mpremote/main.py

-        "exec",
-        "import machine; machine.RTC().datetime((2020, 1, 1, 0, 10, 0, 0, 0))",
-    ],
+    "setrtc": "rtc --set",  # Backwards compatible alias for old command.


Since this never really worked as intended (it set a fixed time...) I think it's safe to just delete it, and the user can add their own shortcut if needed (and this new setrtc alias is not doing the same thing as the old command).

This allows the sequence to be paused (e.g. wait for device, etc). Also removes the t_ms arg in reset/bootloader, because these arguments don't really need to be changed, and keeping them would mean inconsistent units used for time delays. This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>

For example, the `reset` shortcut previously allowed an optional delay, but the argument handling cannot handle `reset next-command` as `next-command` will be interpreted as the delay argument. The fix in this commit allows `reset + next-command`. This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>

Replaces the existing functionality provided by the `setrtc` alias to use the current time, rather than a hard-coded date/time. Use `rtc` to query the current time. Use `rtc --set` to set it. This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>

This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>

Changes in this commit: - Add a extra detail to each of the commands. - Add more about handling options and arguments. - Include shortcut commands that behave like real commands to the command list (e.g. bootloader, rtc). - Add extra information and reword to address common misconceptions, in particular how commands chain together. - Add additional examples showing some more interesting combinations. - Add descriptions to each of the examples. - Add pipx installation instructions. - Describe how user-configuration works. This work was sponsored by Google Season of Docs. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>

jimmo added the season-of-docs-2023 label May 30, 2023

jimmo force-pushed the mpremote-docs-update branch from 7022ccc to 7b5abe3 Compare May 30, 2023 12:39

mattytrentini reviewed May 30, 2023

View reviewed changes

jimmo force-pushed the mpremote-docs-update branch from 7b5abe3 to 132258a Compare May 31, 2023 01:08

dpgeorge added the tools label Jun 2, 2023

dpgeorge reviewed Jun 2, 2023

View reviewed changes

jimmo force-pushed the mpremote-docs-update branch 2 times, most recently from a193e50 to edf33ea Compare June 2, 2023 06:06

jimmo added 5 commits June 2, 2023 16:11

tools/mpremote: Handle cp without destination.

b6b1979

This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>

dpgeorge force-pushed the mpremote-docs-update branch from edf33ea to bd5d016 Compare June 2, 2023 06:18

dpgeorge merged commit bd5d016 into micropython:master Jun 2, 2023
43 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

tools/mpremote: Add `delay` and `rtc` commands. Extend documentation. #11659

tools/mpremote: Add `delay` and `rtc` commands. Extend documentation. #11659

jimmo commented May 30, 2023 •

edited

Loading

github-actions bot commented May 30, 2023

codecov bot commented May 30, 2023 •

edited

Loading

Wind-stormger commented May 30, 2023

mattytrentini left a comment

mattytrentini May 30, 2023

jimmo May 31, 2023

mattytrentini May 30, 2023

jimmo May 31, 2023

mattytrentini May 30, 2023

jimmo May 31, 2023

mattytrentini May 30, 2023

jimmo May 31, 2023

mattytrentini May 30, 2023

jimmo May 31, 2023

jimmo commented May 31, 2023

dpgeorge Jun 2, 2023

jimmo Jun 2, 2023

dpgeorge Jun 2, 2023

jimmo Jun 2, 2023

	This will copy the file to RAM on the device and execute it directly.
	Transfer <file.py> to the device where it will be compiled and executed.

tools/mpremote: Add delay and rtc commands. Extend documentation. #11659

tools/mpremote: Add delay and rtc commands. Extend documentation. #11659

Conversation

jimmo commented May 30, 2023 • edited Loading

github-actions bot commented May 30, 2023

codecov bot commented May 30, 2023 • edited Loading

Codecov Report

Wind-stormger commented May 30, 2023

mattytrentini left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jimmo commented May 31, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tools/mpremote: Add `delay` and `rtc` commands. Extend documentation. #11659

tools/mpremote: Add `delay` and `rtc` commands. Extend documentation. #11659

jimmo commented May 30, 2023 •

edited

Loading

codecov bot commented May 30, 2023 •

edited

Loading