Some use cases and small talk for the mpremote tool.

[Wind-stormger]

I've tried a lot of different 3rd party micropython tools, some are Windows apps, some are VScode plugins.

But when I tried MicroPython's mpremote tool, I almost decided it was going to be my go-to tool. 😄

I usually use it in conjunction with VScode. Its code highlighting, auto-completion, and auto-indentation are very useful. It is also easy to open other plugins at the same time. The important thing is that VScode is also a multi-platform IDE.

Maybe some minimalists, I think the mpremote tool will also be suitable, just use the system's terminal with any text editor, if you are a terminal command line veteran, you only need a terminal to do everything.

Document Page

GitHub Page

PyPI Page

---

Most of the use cases are pretty clear in the documentation, but I'm not a command line veteran, so I'll put some use cases I figured out here, maybe it will help some newbies like me.

Using mpremote 0.3.0 that has been released in PyPI.

Existing use cases for this post:

1. cp
   1.1 Copy file, in the current path of the terminal
   1.2 Copy files，in absolute paths
   1.3 Copy multiple files at the same time
2. exec, run
3. mount
   3.1 Mount the local directory on the remote device
   3.2 Continue to use the script in the original flash after mounting the local directory
   3.3 A way to speed up testing

1. cp

This is probably the most common command besides repl, used to copy files from local to device, or from device to local. Probably because I am not yet familiar with the terminal command syntax, at first I could not fully grasp the usage of the cp command from the several use cases in the documentation.

1.1 Copy the file, in the current path of the terminal

First create a clean temporary folder and write a main.py into it.

print ("start")
for i in range(2):
    print(i)
print ("end")

Simplest use case, enter this folder path in terminal, copy file from local to device :

mpremote connect COM1 cp main.py : 

mpremote connect COM1 cp main.py :main.py

The two commands achieve the exact same function.

After the : symbol, if you enter a filename, the file will be renamed to this filename when copied to the device.

Copy file from device to local :

mpremote connect COM1 cp :main.py .

mpremote connect COM1 cp :main.py main.py

The two commands achieve the exact same function.

If you want to rename, you can delete the . symbol and enter the filename you want.

1.2 Copy files in absolute paths

It is a little more complicated.

On Windows, use the absolute path to the file to copy from local to device:

mpremote connect COM1 cp D:\temp\main.py :main.py

Copy file from device to local :

mpremote connect COM1 cp :main.py D:\temp\main.py

At present, special attention should be paid to the fact that the target filename cannot be omitted in Windows!
Relevant contents have been transferred to issue #9132 .
PR #9148 Support for Windows pathname separators.

In Linux, such as Ubuntu, copy a file from an absolute path can omit the target filename:

mpremote connect /dev/ttyACM0 cp ~/temp/main.py :

mpremote connect /dev/ttyACM0 cp /home/wind/temp/main.py :

mpremote connect /dev/ttyACM0 cp :main.py ~/temp/

mpremote connect /dev/ttyACM0 cp :main.py /home/wind/temp/

1.3 Copy multiple files at the same time

In Linux, such as Ubuntu, copy multiple files from local to device with absolute path :

mpremote connect /dev/ttyACM0 cp ~/temp/main.py ~/temp/main2.py :

Copy multiple files from device to local absolute path:

mpremote connect /dev/ttyACM0 cp :main.py :main2.py ~/temp/

2. exec, run

These commands are used to control the remote device to run Python code or scripts without copying files.

2.1 execute the given Python code

mpremote connect COM1 exec "print(1234)"

Just like entering a line of Python code in REPL.

2.2 run a script from the local filesystem

mpremote connect COM1 run test_1.py

Just like entering paste mode in the REPL, copy and paste the code into the specified Python script, then run it.

3. mount

I haven't thought about this path yet, take a look at the following use case and try to understand it, you'll be as excited as I am.

3.1 Mount the local directory on the remote device

First create a clean temporary directory and write some Python script into it, as follows:

# numbers.py
num_1 = 21
num_2 = 22
num_3 = 23
num_4 = 24

# test_1.py
print("test_1 start")
import numbers
print(numbers.num_1)
print(numbers.num_2)
print(numbers.num_4)
print("test_1 end")

# test_2.py
print("test_2 start")
import numbers
temp1 = numbers.num_3 - numbers.num_2
print(temp1)
temp1 = numbers.num_3 - numbers.num_1
print(temp1)
print("test_2 end")

Enter the path to this directory in the terminal.

Let's confirm some information, list files on the device:

mpremote connect COM1 ls

ls :
         139 boot.py

Enter REPL and confirm again:

mpremote connect COM1 repl

>>> uos.listdir()
['boot.py']
>>>

Exit REPL, mount the local directory, enter repl again:

mpremote connect COM1 mount . repl

Confirm files again:

>>> uos.listdir()
['numbers.py','test_1.py', 'test_2.py']

There is no boot.py here, but the Python script we created appears in the list.

Import and run two test scripts:

>>> import test_1,test_2
test_1 start
21
22
24
test_1 end
test_2 start
1
2
test_2 end
>>>

View a file:

>>> f=open("numbers.py")
>>> print(f.read())
# numbers.py
num_1 = 21
num_2 = 22
num_3 = 23
num_4 = 24

>>>

Beyond surprise, you might wonder, if the script files were all uploaded to the device and stored? which I did initially.

Now, we keep the terminal in REPL, modify this file locally:

# numbers.py
num_1 = 1
num_2 = 12
num_3 = 23
num_4 = 35

Go back to REPL and check again:

>>> f=open("numbers.py")
>>> print(f.read())
# numbers.py
num_1 = 1
num_2 = 12
num_3 = 23
num_4 = 35

>>>

All doubts dissipated, the file was only saved in the local directory, and this directory was mounted on the device.

Soft reset is handled and will re-mount the directory.

@jimmo explained more about this in discussioncomment-3500600 , discussioncomment-3526060

This is like a mobile hard disk, or a NAS, cloud disk, connected to the MicroPython device. Obviously, this function can greatly save the flash life of the device. Usually, you only need to copy the python script file to flash when you have to run it offline.

It is recommended to execute python scripts using the following combined commands:

mpremote connect COM1 mount . exec "import test_1"

3.2 Continue to use the script in the original flash after mounting the local directory

Use the uos.listdir("/") command in the REPL and you will see the files originally stored in flash:

>>> uos.listdir("/")
['remote', 'boot.py', 'main.py']

If you want to use flash scripts (such as main.py) while keeping the local directory mounted, you can use the following command to add the original flash root directory path to the sys.path list:

>>> import sys
>>> sys.path
['', '.frozen', '/lib']
>>> sys.path.append("/")
>>> sys.path
['', '.frozen', '/lib', '/']
>>> import main

If there is already main.py in the mounted local directory, only the main.py of the local directory will be run. You can use reverse() to change the list order:

>>> sys.path
['', '.frozen', '/lib', '/']
>>> sys.path.reverse()
>>> sys.path
['/', '/lib', '.frozen', '']
>>> import main

Scripts in flash will now run first.

3.3 A way to speed up testing

If we need to test and modify a script again and again, and the script has imported many script modules stored locally, in this case, each mount test will take several seconds or even tens of seconds.

I've come up with a way to effectively reduce the runtime by import modules in the REPL that are not duplicated.

Take testing SSD1306 OLED display as an example, main.py is the main program, ssd1306.py is the driver module, and the program code will not be listed in full here.

Use time.tick_ms() to verify the time required to test the main.py script in the local directory, which takes about 6 seconds :

>>> import time;t1 = time.ticks_ms();import main;time.ticks_diff(time.ticks_ms(),t1)
6032

Use sys.modules to view the currently imported script modules, you can see that ssd1306.py has been imported:

>>> import sys;sys.modules
{'main': <module 'main' from 'main.py'>, 'ssd1306': <module 'ssd1306' from 'ssd1306.py'>, 'flashbdev': <module 'flashbdev' from 'flashbdev.py'>}

We just need to remove main and keep the other modules:

>>> del main;sys.modules.pop('main')
<module 'main' from 'main.py'>
>>> import sys;sys.modules
{'ssd1306': <module 'ssd1306' from 'ssd1306.py'>, 'flashbdev': <module 'flashbdev' from 'flashbdev.py'>}

Test again:

>>> import time;t1 = time.ticks_ms();import main;time.ticks_diff(time.ticks_ms(),t1)
1612

Significantly improved!

( To Be Continued)

[ThinkTransit]

This is a good start, one of the things I struggle with is how to sync/copy a local directory to a device. I can never get the command correct and I always default back to Thonny when copying lots of files.

Would be great to have some sort of sync command that only uploads changed files etc...

[ThinkTransit]

Thanks @bulletmark this is very useful.

[Wind-stormger]

This makes the device transparently mount the filesystem from the host PC and so it will load your Python files directly from there. (It's a really cool feature)

It's really cool, but I'm a little confused about transparently mount the filesystem.

Is it temporarily mounted into Flash, or in RAM, or somewhere else? Maybe it's not temporarily?

Where are the mounted files after hard reset or soft reset?

[jimmo]

Is it temporarily mounted into Flash, or in RAM, or somewhere else? Maybe it's not temporarily?

Neither. It's like connecting to a network drive -- if you've ever used Windows File Sharing (CIFS/SMB) to open a network share, it's the same idea. The files aren't actually on your computer, they're accessed over the network.

mpremote mount works the same way -- when the device accesses the files, they're transparently fetched over the serial connection.

The key thing is that unlike Windows, Unix-like systems (and MicroPython) use a VFS where all filesystems are "mounted" into the common filesystem namespace starting at the root /. (i.e. there are no drive letters, etc).

[jimmo]

Where are the mounted files after hard reset or soft reset?

Hard reset would disconnect mpremote. Soft reset is handled and will re-mount the directory.

Something I just realised though, much of this terminology like "VFS" and "mount" is very Linux-specific (technically Unix-specific but most Mac users probably aren't as exposed to it in quite the same way). Like it was immediately obvious to me what this command would do, but that's only because I come from a Linux world... so the docs could probably be improved by being less reliant on this pre-existing knowledge.

[Wind-stormger]

when the device accesses the files, they're transparently fetched over the serial connection.

I was shocked by what you said.
I immediately carried out a lot of tests. It was so cool.
I will update some use cases in my post to show these.

[jimmo]

Thanks @Wind-stormger

Just to repeat the same comment I made on the original forum post -- the ./ behavior is about to go away. See #9091. The goal is to make it behave exactly like scp (which is where the :remote syntax comes from).

[Wind-stormger]

When the new version is released to pypi, I will also try it and update the post.

[Wind-stormger]

Hey~ @jimmo
In Windows, whether it is copying a file in an absolute path or a file in a folder in a relative path, an error will occur.

Regarding the path format in Windows, I think this method can be used to judge the current system, and then apply the corresponding path format to operate the file.

import platform
print(platform.system())
 
if(platform.system()=='Windows'):
    pass
elif(platform.system()=='Linux'):
    pass
else:
    pass

[jimmo]

hi @Wind-stormger could you please provide more details about the error you see? Screenshots or copy+paste from terminal would be fine.

[jimmo]

Sorry, I see you raised #9132. Thanks

[mdaeron]

Your post prompted me to take a look at mpremote for the first time (I use rshell most of the time). One great feature is the ability to automatically connect to the first free device when several boards are physically connected to the computer. Sadly, on a Mac, the first free device is always /dev/cu.Bluetooth-Incoming-Port. I tried various commands and asked here, but so far haven't been able to solve the issue.

Is there a clever way to configure mpremote so that it always ignores /dev/cu.Bluetooth-Incoming-Port?

[jimmo]

First question: Would it be worth it to create a PR on the official micropython and find out whether it's useful enough to be merged? This is all new to me.

Yes please! This bug has been reported a few times but (as you can probably guess) everyone who has contributed to mpremote so far uses Linux.

Second question: If I were to do so, how/where should I edit the docs to describe this new functionality?

I'm not sure ... the docs currently say "This command automatically detects and connects to the first available serial device and provides an interactive REPL." and if you were to fix this bug then it would be making that statement actually true. So I don't think you need to update the docs.

[mdaeron]

Yes please!

OK, will do.

So I don't think you need to update the docs.

But the fix depends on manually defining autoconnect_regexp as something that makes sense for your system. This should be stated somewhere, right? I suspect this would go in micropython/docs/reference/mpremote.rst, and maybe in a docstring somewhere. I'll look into it.

Another option would be to define sensible default regexp values for each system, but I wouldn't know what to specify for Linux or Windows.

[mdaeron]

PR #9140

[bulletmark]

I don't think that PR is a good idea. Since the docs say "This command automatically detects and connects to the first available serial device" and Macs for some reason are not doing that then surely the solution is to fix that automatic connection logic rather than add an obscure "autoconnect_regexp" option which users are required to discover and configure?

[mdaeron]

I don't think that PR is a good idea. Since the docs say "This command automatically detects and connects to the first available serial device" and Macs for some reason are not doing that then surely the solution is to fix that automatic connection logic rather than add an obscure "autoconnect_regexp" option which users are required to discover and configure?

Fair point. I agree that solving the auto connect bug and adding an option to filter ports are two separate issues.

I'll look into it but I'll probably have questions about Linux/Windows ports. In the interest of keeping this discussion in a single place, would you care to copy that comment to the PR itself please?

[Wind-stormger]

I updated the chapter on mount , and optimized the cp.
mount is a great feature, take a look.

@mdaeron @ThinkTransit

[jimmo]

hi @Wind-stormger

Also, the files in the original device directory cannot be used until an umount command or a hard reset.

That's actually not the case.

Before you do the mpremote mount, the on-board flash filesystem is mounted at /. So for example, you have /boot.py. The board (like your command prompt) has a concept of the current working directory, which is /.

When you mpremote mount, a directory is created /remote and this is the mount point for the remote connection. Then mpremote does os.chdir() to change the working dir to /remote.

So if you did os.listdir("/") you'd see ["/remote", "boot.py", ...etc].

If you want to import files from device, you can add "/" to sys.path, i.e. sys.path.append("/").

This behavior is by design -- the default is to make the on-device files available-but-not-importable-by-default. Then you can use sys.path to make them available if you want.

(Edit: Just a minor correction to what I said above -- on the stm32 port, the built-in flash is mounted at "/flash". On all other ports it's mounted at "/". I'm not sure of the history there and why the stm32 behavior wasn't matched on subsequent ports)

[Wind-stormger]

Thanks for sharing these details @jimmo

When you mpremote mount, a directory is created /remote and this is the mount point for the remote connection. Then mpremote does os.chdir() to change the working dir to /remote.

When you mentioned this, I thought of os.listdir('/sd')，but , because I haven't tried to actually use an SD card, I didn't expect that they might have commonality.

I will continue to follow up and revise the relevant description.

Besides，is there any way to automatically run the boot.py and main.py scripts after hanging in the local directory, as usual?

[jimmo]

Besides，is there any way to automatically run the boot.py and main.py scripts after hanging in the local directory, as usual?

Not quite sure what you mean sorry...

You can run a script automatically when mounting with a command like: mpremote mount . exec "import foo" repl

[Wind-stormger]

You can run a script automatically when mounting with a command like: mpremote mount . exec "import foo" repl

Of course, this is already shown in the documentation.
I mean, after mounting, without using exec "import boot,main", boot.py and main.py in the mount directory are still automatically run.

Okay , never mind😁, let's just use mpremote mount . exec "import boot,main".

[Wind-stormger]

Update,add:
3.2 Continue to use the script in the original flash after mounting the local directory
3.3 A way to speed up testing

[zcattacz]

It would be great if it can also connect ws://ip:port for repl.

[bixb922]

Great description, very useful!
Instead of
mpremote connect COM1 mount . exec "import test_1"
you also can write a bit less this way :
mpremote mount . run test_1.py

[peterhinch]

I'd recommend users of mpremote to look at this repo. It allows you to add your own Python scripts to mpremote. These are just dropped into a directory and they become documented commands. I find this mega useful. So I can do things like

$ mpremote wfif_connect
$ mpremote wifi_scan
$ mpremote exec "host='192.168.0.10';offset=1" ntptime

The last sets the device RTC from a local NTP server with a local time offset of 1hr. A command can of course be scripted, or be the target of an alias. Pure magic...

[Wind-stormger]

Surprise, I'll try something~

[JoGeDuBo]

In all my use cases I need to set the RTC of the Pico Pi.
But the command "mpremote setrtc" sets it to a fixed time (why?).

So I changed the file mpremote/main.py (version 1.20.0) as follows:

exchange the line 314

   "import machine; machine.RTC().datetime((2020, 1, 1, 0, 10, 0, 0, 0))"

by

   f"import machine; machine.RTC().datetime({_rtc_datetime})" 

and insert somewhere at the beginning (line 44):

    from time import localtime
    _rtc_datetime = (t:=localtime())[:3]+(0,)+t[3:6]+(0,)

Now the time of the Pico Pi is always set to the local time of the PC.

[peterhinch]

You could raise a PR. It's puzzled me why setrtc doesn't do this.

[Josverl]

I started a PR for this , and then ran into the reality that different ports require different inputs.
Also see

• ports/rtc: Inconsistencies between ports and the documentation. #10578
• tools/mpremote: Support {{template expressions}} for exec. #9861

[peterhinch]

The existing code assumes that rtc.datetime() works as per the docs. Perhaps we can assume that all ports will eventually conform. Rejecting a PR on the grounds that it's based on the same assumptions as master would seem perverse...

[jimmo]

You could raise a PR. It's puzzled me why setrtc doesn't do this.

Indeed, me too! I included a more useful setrtc (and getter) in #11659

It does of course have the limitation that it assumes the port's implementation of RTC works as per the docs. I might try and see if I can at least detect ports that behave differently, but we will eventually fix this (MicroPython 2.0).

(Although a couple of recent threads arising from significantly more minor compatibility fixes have made me possibly reconsider ever changing anything again broken or otherwise!).

[zcattacz]

bug? fs cp doesn't seem to be able to copy binary file, while the webrepl webpage console's file upload works.

[Wind-stormger]

Show more details and process?

[zcattacz]

Nah, I must have missed the ":/" part. Was really new to this. So far it works just fine.

[zcattacz]

Well, I think that is a bug though, since when cp has the target not specified, it would report error missing destination ..., natually ppl expect the same behavior from other cp variants.

[jimmo]

@zcattacz thanks, yes, I agree. I've fixed this in #11659 :

$ mpremote cp foo.py
cp: missing destination file operand after 'foo.py'

[jimmo]

I tried to address some of the comments from this thread in a documentation update for mpremote. Please feel free to comment there: #11659