Using ampy you can take Python code written on your computer and run it on a connected MicroPython board. This gives you a simple workflow for exploring MicroPython. Write code on your computer in your favorite text editor, then use ampy's run command to run it on a board!
To use the run command just specify a path to a Python file on your computer. Ampy will send the file to the board, wait for it to finish running, and print any output from the program.
For example create a file test.py on your computer and save inside it the following Python code:
print('Hello world! I can count to 10:')
for i in range(1,11):
print(i)
In a terminal in the same directory as test.py run the following ampy command to execute the script on a connected MicroPython board:
ampy --port /serial/port run test.py
Where /serial/port is the path or name of the serial port connected to the MicroPython board.
You should see the output of the code after it was run on the board:
If you receive an error that ampy failed to receive the expected response be sure you disabled debug output as mentioned at the top of the page! Also double check the board is connected to your computer and you are specifying the correct serial port for the board. Be sure the file test.py is in the same directory as you're running the ampy command too.
Be aware the run command is not a shell or tool that allows you to send input from your computer to the board! If you need to send input you'll want to connect to the board and use its serial REPL.
By default the run command will wait for the script to finish running on the board before printing its output. In some cases you don't want this behavior--for example if your script has a main or infinite loop that never returns you don't want ampy to sit around waiting forever for it to finish. In this case add the --no-output option to the run command. This flag tells ampy not to wait for any output and instead just start running the script and return.
For example modify the test.py script so that it counts numbers forever in an infinite loop:
import time
print('Hello world! I can count:')
i = 1
while True:
print(i)
i += 1
time.sleep(1.0) # Delay for 1 second.
Then run it with the --no-output option and notice it immediately returns:
ampy --port /serial/port run --no-output test.py
However open the board's serial REPL and watch it count numbers every second!
Remember the program is still running, ampy just didn't wait for it to stop!
The --no-output option is great for writing scripts that are like an Arduino sketch. In Arduino you have an explicit setup and loop function which you fill in with code that runs once (in setup) and code that runs forever (in loop). MicroPython doesn't have exactly the same concept, but you can create it yourself in your own Python scripts!
In fact look at the test.py above and notice all the code before the while True loop is like the setup function from an Arduino sketch, it's executed just once at the start of the program. Then the code inside the while True loop is like the loop function from Arduino, this code runs repeatedly as fast as possible. To make it a little more clear here's the test.py with comments that show where the setup code goes and where the loop code goes:
###########################################################################
# Setup code goes below, this is called once at the start of the program: #
###########################################################################
import time
print('Hello world! I can count:')
i = 1
while True:
###################################################################
# Loop code goes inside the loop here, this is called repeatedly: #
###################################################################
print(i)
i += 1
time.sleep(1.0) # Delay for 1 second.
If you're coming to MicroPython with a background in Arduino, consider writing your MicroPython scripts in a similar style as the above. Put your setup code first and then a main loop that runs forever. Just be sure you add the --no-output option when running with ampy so it knows not to wait for the script to finish!
