Skip to content

Commit 84f1fdf

Browse files
dlechdlech
committed
README: update for installing from pypi
1 parent 4000ad8 commit 84f1fdf

File tree

3 files changed

+159
-110
lines changed

3 files changed

+159
-110
lines changed

‎README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Pybricks tools & interface library
2+
3+
This is a package with tools for Pybricks developers. For regular users we
4+
recommend the [Pybricks Code][code] web IDE.
5+
6+
This package contains both command line tools and a library to call equivalent
7+
operations from within a Python script.
8+
9+
[code]: https://www.code.pybricks.com
10+
11+
## Installation
12+
13+
### Python Runtime
14+
15+
We currently only support Python 3.8.x. (Newer versions are not supported yet
16+
for technical reasons.)
17+
18+
- For Windows, use the [official Python installer][py-dl] or the [Windows Store][py38-win].
19+
- For Mac, use the [official Python installer][py-dl] or Homebrew (`brew install [email protected]`).
20+
- For Linux, use the distro provided `python3.8` or if not available, use a Python
21+
runtime version manager such as [asdf][asdf] or [pyenv][pyenv].
22+
23+
24+
[py-dl]: https://www.python.org/downloads/
25+
[py38-win]: https://www.microsoft.com/en-us/p/python-38/9mssztt1n39l
26+
[asdf]: https://asdf-vm.com
27+
[pyenv]: https://github.com/pyenv/pyenv
28+
29+
### Command Line Tool
30+
31+
We recommend using [pipx][pipx] to install `pybricksdev` as a command line tool.
32+
33+
[pipx]: https://pipxproject.github.io/pipx/
34+
35+
Be sure to install `pipx` in the Python 3.8 runtime:
36+
37+
python3.8 -m pip install --update pip # ensure pip is up to date first
38+
python3.8 -m pip install pipx
39+
40+
If this is the first time you have installed `pipx`, run this command:
41+
42+
python3.8 -m pipx ensurepath
43+
44+
This will make it so that tools installed with `pipx` are in your `PATH`.
45+
You will need to restart any terminal windows for this to take effect. If that
46+
doesn't work, try logging out and logging back in.
47+
48+
Then use `pipx` to install `pybricksdev`:
49+
50+
python3.8 -m pipx install pybricksdev
51+
52+
#### Windows users
53+
54+
If you are using the *Python Launcher for Windows* (installed by default with
55+
the official Python installer), then you will need to use `py -3.8` instead
56+
of `python3.8`.
57+
58+
py -3.8 -m pip install --update pip # ensure pip is up to date first
59+
py -3.8 -m pip install pipx
60+
py -3.8 -m pipx ensurepath
61+
py -3.8 -m pipx install pybricksdev
62+
63+
#### Linux USB
64+
65+
On Linux, `udev` rules are needed to allow access via USB. The `pybricksdev`
66+
command line tool contains a function to generate the required rules. Run the
67+
following:
68+
69+
pybricksdev udev | sudo tee /etc/udev/rules.d/99-pybricksdev.rules
70+
71+
### Library
72+
73+
To install `pybricksdev` as a library, we highly recommend using a virtual
74+
environment for your project. Our tool of choice for this is [poetry][poetry]:
75+
76+
poetry env use python3.8
77+
poetry add pybricksdev
78+
79+
Of course you can always use `pip` as well:
80+
81+
pip install pybrickdev --pre
82+
83+
84+
[poetry]: https://python-poetry.org
85+
86+
87+
## Using the Command Line Tool
88+
89+
The following are some examples of how to use the `pybricksdev` command line tool.
90+
For additional info, run `pybricksdev --help`.
91+
92+
### Flashing Pybricks MicroPython firmware
93+
94+
Make sure the hub is off. Press and keep holding the hub button, and run:
95+
96+
pybricksdev flash ../pybricks-micropython/bricks/technichub/build/firmware.zip
97+
98+
Replace the example path with the path to the firmware archive. Decrease the
99+
delay `d` between data packages for faster transfer. Increase the delay if it
100+
fails.
101+
102+
You may release the button once the progress bar first appears.
103+
104+
The SPIKE Prime Hub and MINDSTORMS Robot Inventor Hub do not have a Bluetooth
105+
bootloader. It is recommended to [install Pybricks using a Python script][issue-167] that
106+
runs on the hub. You can also flash the firmware manually using [DFU](dfu).
107+
108+
109+
[dfu]: ./README_dfu.rst
110+
[issue-167]: https://github.com/pybricks/support/issues/167
111+
112+
113+
### Running Pybricks MicroPython programs
114+
115+
This compiles a MicroPython script and sends it to a hub with Pybricks
116+
firmware.
117+
118+
pybricksdev run --help
119+
120+
#
121+
# ble connection examples:
122+
#
123+
124+
# Run a one-liner on a Pybricks hub
125+
pybricksdev run ble "Pybricks Hub" "print('Hello!'); print('world!');"
126+
127+
# Run script on the first device we find called Pybricks hub
128+
pybricksdev run ble "Pybricks Hub" demo/shortdemo.py
129+
130+
# Run script on device with address 90:84:2B:4A:2B:75 (doesn't work on Mac)
131+
pybricksdev run ble 90:84:2B:4A:2B:75 demo/shortdemo.py
132+
133+
#
134+
# Other connection examples:
135+
#
136+
137+
# Run script on ev3dev at 192.168.0.102
138+
pybricksdev run ssh 192.168.0.102 demo/shortdemo.py
139+
140+
# Run script on primehub at
141+
pybricksdev run usb "Pybricks Hub" demo/shortdemo.py
142+
143+
144+
### Compiling Pybricks MicroPython programs without running
145+
146+
This can be used to compile programs. Instead of also running them as above,
147+
it just prints the output on the screen instead.
148+
149+
pybricksdev compile demo/shortdemo.py
150+
151+
pybricksdev compile "print('Hello!'); print('world!');"
152+
153+
154+
This is mainly intended for developers who want to quickly inspect the
155+
contents of the `.mpy` file. To get the actual file, just use `mpy-cross`
156+
directly. We have used this tool in the past to test bare minimum MicroPython
157+
ports that have neither a builtin compiler or any form of I/O yet. You can
158+
paste the generated `const uint8_t script[]` directly ito your C code.

‎README.rst‎

Lines changed: 0 additions & 109 deletions
This file was deleted.

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description = "Pybricks developer tools"
55
authors = ["The Pybricks Authors <[email protected]>"]
66
maintainers = ["Laurens Valk <[email protected]>", "David Lechner <[email protected]>" ]
77
license = "MIT"
8-
readme = "README.rst"
8+
readme = "README.md"
99
homepage = "https://pybricks.com"
1010
repository = "https://github.com/pybricks/pybricksdev"
1111
classifiers = [

0 commit comments

Comments
 (0)