Command line tool for wireless Micropython devices
Project description
uPydev
Command line tool for wireless Micropython devices
uPydev is an acronym of 'Micropython device', and it is intended to be a command line tool to make easier the development, prototyping and testing process of devices based on boards running Micropython.
It is a command line tool for 'wireless Micropython devices' since it make use of the WebREPL protocol to provide communication with and control of the device.
*uPydev is built on top of other tools/scripts which are:
The core is 'webrepl_client.py ' : a Terminal WebREPL protocol as seen in this WebREPL pull request by @Hermann-SW
Other tools are:
'webrepl_cli.py' for the file transfer protocol (from the WebREPL repo of micropython) (modified and named 'upytool')
'esptool.py' to flash the firmware into esp boards
'mpy-cross' to compile .py scripts into .mpy files.
Keep in mind that this project is in ALPHA state, sometimes, some commands may not work/return anything
Features:
- Command line wireless communication/control of micropython devices.
- Terminal WebREPL protocol
- Custom commands to automate communication/control
- Command line autocompletion
Getting Started
First be sure that the WebREPL daemon is enabled and running see webrepl-a-prompt-over-wifi and
webrepl-web-browser-interactive-prompt
Requirements:
WebREPL enabled
Python modules (automatically installed using pip):
argcomplete (for command line autocompletion)
Tested on:
MacOS X (Mojave 10.14.5)
Raspbian GNU/Linux 9 (stretch) (through ssh session)
For Raspbian pip install mpy-cross
seems to fail, so to install upydev without mpy-cross do:
$ git clone https://github.com/Carglglz/upydev.git
[...]
$ cd upydev
$ sudo pip3 install . -r rpy_rqmnts.txt
upy Boards:
Esp32 Huzzah feather
Esp8266 Huzzah feather
Installing using pip:
$ pip install upydev
Quick Reference:
Help:
In CLI do :
$ upydev -h
Configurate uPy Device:
1st step: Configurate upy device target and password:
-
To save configuration in working directory:
$ upydev config -t [UPYDEVICE IP] -p [PASSWORD]
example:
$ upydev config -t 192.168.1.58 -p mypass
-
To save configuration globally use -g option:
$ upydev config -t [UPYDEVICE IP] -p [PASSWORD] -g t
example:
$ upydev config -t 192.168.1.58 -p mypass -g t
upydev will use local working directory configuration unless it does not find any or manually indicated with -g option.
uPydev Usage:
Usage:
$ upydev [Mode] [options] or upydev [upy command] [options]
This means that if the first argument is not a Mode keyword or a upy command keyword it assumes it is a 'raw' upy command to send to the upy device
Example: Mode
$ upydev put -f dummy.py
Example: uPy command
$ upydev info
Example: Raw commands
$ upydev "my_func()"
$ upydev 2+1
$ upydev "import my_lib;foo();my_var=2*3"
uPydev Mode/Tools:
-
config : to save upy device settings (see -p, -t, -g), so the target and password arguments wont be required any more
-
put : to upload a file to upy device (see -f, -s and -rst; for multiple files see -fre option)
-
get : to download a file from upy device (see -f and -s; for multiple files see -fre option)
-
sync : for a faster transfer of large files (this needs sync_tool.py in upy device) (see -f, -s and -lh; for multiple files see -fre option)
> sync_tool.py is under upyutils directory
-
cmd : for debugging purpose, to send command to upy device ; (see -c, -r, -rl);
- Examples:
$ upydev cmd -c "led.on()"
$ upydev cmd -r "print('Hello uPy')"
$ upydev cmd -rl "function_that_print_multiple_lines()"
- tip: simple commands can be used without quotes; but for commands with parenthesis or special characters use quotes, for example: 'dummy_func()' ; use double quotes "" when the command includes a string like this example: "uos.listdir('/sd')"
-
wrepl : to enter the terminal webrepl; write exit or press CTRL-C to exit (see Terminal WebREPL protocol for more information)
-
srepl : to enter the terminal serial repl using picocom, indicate port by -port option (to exit do CTRL-a, CTRL-x) (see: Picocom for more information)
-
ping : pings the target to see if it is reachable, CTRL-C to stop
-
run : just calls import 'script', where 'script' is indicated by -f option (script must be in upy device or in sd card indicated by -s option and the sd card must be already mounted as 'sd');
Supports CTRL-C to stop the execution and exit nicely.
-
install : install libs to '/lib' path with upip; indicate lib with -f option
-
mpyx : to froze a module/script indicated with -f option, and save some RAM, it uses mpy-cross tool (see mpy-cross for more information)
-
timeit: to measure execution time of a module/script indicated with -f option.
This is an adapted version of timed_function
-
fw: to list or get available firmware versions, use -md option to indicate operation: - to list do: "upydev fw -md list -b [BOARD]" board should be 'esp32' or 'esp8266' (web scraping from micropython downloads page ) - to get do: "upydev fw -md get [firmware file]" (uses curl) - to see available serial ports do: "upydev fw -md list serial_ports"
-
flash: to flash a firmware file to the upydevice, a serial port must be indicated to flash do: "upydev flash -port [serial port] -f [firmware file]"
-
see: to get specific command help info indicated with -c option
-
make_group: to make a group of boards to send commands to. Use -f for the name of the group
and -devs option to indicate a name, ip and the password of each board. (To store the group settings globally use -g option)
GROUP COMMAND MODE (-G option):
To send a command to multiple devices in a group (made with make_group command) use -G option
Usage: upydev [command] -G [GROUP NAME]
To target specific devices within a group add -devs option as -devs [DEV_1 NAME] [DEV_2 NAME]
upydev will use local working directory configuration unless it does not find any or manually indicated with -g option
GROUP COMMAND PARALLEL MODE (-GP option):
To send a command at the same time to multiple devices in a group (made with make_group command) use -GP option.
**Be aware that not all the commands are suitable for parallel execution (wrepl for example)
Usage: upydev [command] -GP [GROUP NAME]
To target specific devices within a group add -devs option as -devs [DEV_1 NAME] [DEV_2 NAME]
upydev will use local working directory configuration unless it does not find any or manually indicated with -g option
uPydev Commands:
uPy commands are organized in:
-
General: These commands should work 'out of the box' in any Micropython running board with WebREPL daemon enabled.
-
SD: These commands need sdcard.py in the upy device, and a sd module/shield at least.
-
INPUT: These commands need a specific sensor module and the appropriate script in the upydevice (All these scripts are under upyutils directory)
- ADC: commands that make use of the ADCs from the board, or an external ADC module (ADS1115) (for external module needs 'ads1115.py' and 'init_ADS.py')
- IMU: commands that make use of the LSM9DS1 module, although other IMU modules could be easily implemented (needs 'lsm9ds1.py' and 'init_MY_IMU.py')
- WEATHER: commands that make use of the BME280 module, although other weather sensor modules could be easily implemented (needs 'bme280.py' and 'init_BME280.py')
- POWER: commands that make use of the INA219 module.
-
OUTPUT: These commands use the DAC or PWM of the board, some needs an actuator module (buzzer or motor driver and a motor) at least and the appropriate script in the upydevice.
- DAC: to generate an analog signal (dc value, sine wave or square wave at the momment) (needs 'dac_signal_gen.py')
- BUZZER: to drive a buzzer with PWM (needs 'buzzertools.py')
- DC MOTOR: to control a DC motor (needs a motor driver and the appropriate script) (needs 'dcmotor.py')
- SERVO: to drive a servo motor (needs 'servo.py')
- STEPPER MOTOR: to drive stepper motor (needs a motor driver and 'stepper.py')
-
NETWORKING:
- MQTT: commands to connect to a broker, subscribe to topic, publish and receive messages (needs 'mqtt_client.py')
- SOCKETS: commands to start client/server socket and send/receive messages (needs 'socket_client_server.py')
- UREQUEST: commands to make http requests, and get json or text output
-
PORT/BOARD SPECIFIC COMMANDS:
- battery : if running on battery, gets battery voltage (esp32 huzzah feather)
- pinout : to see the pinout reference/info of a board, indicated by -b option, to request a single or a list of pins info use -po option (currently just esp32 huzzah feather)
- specs : to see the board specs, indicated by -b option (currently just esp32 huzzah feather)
- pin_status: to see pin state, to request a specific set use -po option
Extensive explanation:
For an extensive explanation and commands demo see Documentation.
Addiontal Scripts for some commands:
The commands that need additional scripts in the upy device are under the uPyutils folder.
For more info see upyutils_docs.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.