This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
wiki:v2:python [2021/12/03 19:04] kees 2021-12-03: created |
wiki:v2:python [2021/12/30 14:48] kees Some minor changes |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | **!!This page is under construction!!** | ||
- | |||
====== Pixy2 Python tutorial ====== | ====== Pixy2 Python tutorial ====== | ||
Line 17: | Line 15: | ||
In this tutorial we will describe the following platforms: | In this tutorial we will describe the following platforms: | ||
- | * Raspberry Pi: using USB and the libpixyusb2 library. | ||
* LEGO Mindstorms EV3 using Python on the ev3dev operating system. | * LEGO Mindstorms EV3 using Python on the ev3dev operating system. | ||
* LEGO Mindstorms EV3 using MicroPython with PyBricks. | * LEGO Mindstorms EV3 using MicroPython with PyBricks. | ||
+ | * Raspberry Pi: using USB and the libpixyusb2 library. | ||
- | This tutorial belongs to Pixy2. If you own the previous Pixy, go to the | + | This tutorial belongs to Pixy2 and Pixy2.1. If you own the previous Pixy, go |
- | chapter "Pixy for LEGO Mindstorms" in the tutorial | + | to the chapter "Pixy for LEGO Mindstorms" in the tutorial |
- | [[https://github.com/KWSmit/Pixy_ev3dev|over here]]. That tutorial is written | + | [[https://github.com/KWSmit/Pixy_ev3dev|over here]], written |
- | by one of our customers. | + | by one of our customers which explains how to use Pixy on LEGO Mindstorms EV3. |
- | + | ||
- | ===== Rasberry Pi ===== | + | |
- | + | ||
- | <Work in progress> | + | |
===== LEGO Mindstorms EV3 ===== | ===== LEGO Mindstorms EV3 ===== | ||
Line 54: | Line 48: | ||
page. | page. | ||
- | ==== API ==== | + | ==== pixycamev3 ==== |
To make programming more easy for you, we developed a Python API to use Pixy2 | To make programming more easy for you, we developed a Python API to use Pixy2 | ||
- | on the EV3. The same API can be used with both Python3 and MicroPython. The | + | on the EV3. To use this API you have to install module ''pixycamev3''. |
+ | The same API can be used with both Python3 and MicroPython. The | ||
only difference is the way you install the API. When installed, using our | only difference is the way you install the API. When installed, using our | ||
API with Python3 is exactly the same as with MicroPython. But first you have | API with Python3 is exactly the same as with MicroPython. But first you have | ||
Line 65: | Line 60: | ||
First configure Pixy2 to communicate over ''I2C''. For this you can use the | First configure Pixy2 to communicate over ''I2C''. For this you can use the | ||
- | PixyMon tool. Connect Pixy2 with the USB cable to your computer and run | + | PixyMon tool. You can find a full reference of PixyMon [[wiki:v2:pixymon_index|here]]. |
+ | Connect Pixy2 with the USB cable to your computer and run | ||
PixyMon. In PixyMon open the configure dialog and select the ''Interface'' tab. | PixyMon. In PixyMon open the configure dialog and select the ''Interface'' tab. | ||
Line 79: | Line 75: | ||
PixyMon and detach Pixy2 from your computer. | PixyMon and detach Pixy2 from your computer. | ||
- | ==== Installing Python API ==== | + | ==== Installing pixycamev3 ==== |
- | This Python API works both with Python3 and MicroPython. | + | This Python API works both with Python3 and MicroPython. There are two ways |
+ | you can walk to use the API: | ||
- | <TODO: explain how to add python file with API to the project or how to | + | === 1. Installing with ''pip'' === |
- | install the API with ''pip''. In case of installing with ''pip'' explain how | + | |
- | to install for Python3 and MicroPython> | + | |
- | ==== Using Python API ==== | + | > At the moment this method only works for Python3. |
+ | |||
+ | First login to your EV3 using ''ssh''. Run the following command | ||
+ | in a terminal window on your computer: | ||
+ | |||
+ | <code> | ||
+ | $ ssh [email protected] | ||
+ | </code> | ||
+ | |||
+ | where ''robot'' is the default username in ev3dev and ''xxx.xxx.xxx.xxx'' | ||
+ | is the IP-address of your EV3. You will be asked for a password. The default | ||
+ | password is ''maker''. Be sure to use you're own combination of username and | ||
+ | password if you changed the default in ev3dev. | ||
+ | |||
+ | When logged in to EV3, you can install the API package on your EV3 with: | ||
+ | |||
+ | <code> | ||
+ | $ python3 -m pip install pixycamev3 | ||
+ | </code> | ||
+ | |||
+ | This takes about four minutes on the EV3. ''pip'' is not installed | ||
+ | out-of-the-box on ev3dev. You can install ''pip'' with: | ||
+ | |||
+ | <code> | ||
+ | $ sudo apt install python3-pip | ||
+ | </code> | ||
+ | |||
+ | Beware this takes about 18 minutes on the EV3! But you can use | ||
+ | ''pip'' later on to install other python packages when needed. | ||
+ | |||
+ | When package ''pixycamev3'' is installed you're ready to program! Go | ||
+ | to the next paragraph [[#Using Python API|Using Python API]]. | ||
+ | |||
+ | === 2. Adding the API to your project folder === | ||
+ | |||
+ | This method works for both Python3 and MicroPython. | ||
+ | |||
+ | In your project folder create a new folder ''pixycamev3''. Visit the repository | ||
+ | on [[https://github.com/charmedlabs/pixycamev3/tree/main/pixycamev3|Github]]. | ||
+ | Add the file pixy2.py to your folder ''pixycamev3''. The easiest way is to open | ||
+ | this file in Github and click on the ''Raw'' button right above the code window. | ||
+ | Then select all text of the file and copy it to a new file named ''pixy2.py'' | ||
+ | in your ''pixycamev3'' folder. | ||
+ | |||
+ | Your project folder structure should look like this: | ||
+ | |||
+ | <code> | ||
+ | project | ||
+ | ├── pixycamev3 | ||
+ | │ └── pixy2.py | ||
+ | └── main.py | ||
+ | </code> | ||
+ | |||
+ | The file ''pixy2.py'' works for both Python and MicroPython. When you copied | ||
+ | the file you're ready to program! | ||
+ | |||
+ | ==== Using pixycamev3 ==== | ||
The main object you will need is the ''Pixy2'' class. This object contains all | The main object you will need is the ''Pixy2'' class. This object contains all | ||
Line 102: | Line 153: | ||
| **Example:** ^^ | | **Example:** ^^ | ||
| <code> | | <code> | ||
- | from pixy2 import Pixy2 | + | from pixycamev3.pixy2 import Pixy2 |
pixy2 = Pixy2(port=1, i2c_address=0x54) | pixy2 = Pixy2(port=1, i2c_address=0x54) | ||
Line 109: | Line 160: | ||
Object ''Pixy2'' contains the following methods: | Object ''Pixy2'' contains the following methods: | ||
- | ^ get_version() ^^ | + | ^ %%get_version()%% ^^ |
| **Description:** ^^ | | **Description:** ^^ | ||
| Get the firmware and hardware version of Pixy2. ^^ | | Get the firmware and hardware version of Pixy2. ^^ | ||
Line 121: | Line 172: | ||
| **Example:** ^^ | | **Example:** ^^ | ||
| <code> | | <code> | ||
- | from pixy2 import Pixy2 | + | from pixycamev3.pixy2 import Pixy2 |
- | prixy2 = Pixy2(port=1, i2c_address=0x54) | + | pixy2 = Pixy2(port=1, i2c_address=0x54) |
# Get version | # Get version | ||
Line 142: | Line 193: | ||
| **Example:** ^^ | | **Example:** ^^ | ||
| <code> | | <code> | ||
- | from pixy2 import Pixy2 | + | from pixycamev3.pixy2 import Pixy2 |
- | prixy2 = Pixy2(port=1, i2c_address=0x54) | + | pixy2 = Pixy2(port=1, i2c_address=0x54) |
# Get frame resolution | # Get frame resolution | ||
Line 163: | Line 214: | ||
| <code> | | <code> | ||
from time import sleep | from time import sleep | ||
- | from pixy2 import Pixy2 | + | from pixycamev3.pixy2 import Pixy2 |
- | prixy2 = Pixy2(port=1, i2c_address=0x54) | + | pixy2 = Pixy2(port=1, i2c_address=0x54) |
# Turn upper leds on for 2 seconds, then turn off | # Turn upper leds on for 2 seconds, then turn off | ||
Line 173: | Line 224: | ||
</code> ^^ | </code> ^^ | ||
- | ^ set_mode(mode) ^^ | + | ^ %%set_mode(mode)%% ^^ |
| **Description:** ^^ | | **Description:** ^^ | ||
| Set mode for Pixy2 (for linetracking) ^^ | | Set mode for Pixy2 (for linetracking) ^^ | ||
| **Parameters:** ^^ | | **Parameters:** ^^ | ||
| mode | Desired mode: | | | mode | Desired mode: | | ||
- | | ::: | Pixy2Mode.LINE_MODE_DEFAULT | | + | | ::: | %%Pixy2Mode.LINE_MODE_DEFAULT%% | |
- | | ::: | Pixy2Mode.LINE_MODE_TURN_DELAYED | | + | | ::: | %%Pixy2Mode.LINE_MODE_TURN_DELAYED%% | |
- | | ::: | Pixy2Mode.LINE_MODE_MANUAL_SELECT_VECTOR | | + | | ::: | %%Pixy2Mode.LINE_MODE_MANUAL_SELECT_VECTOR%% | |
- | | ::: | Pixy2Mode.LINE_MODE_WHITE_LINE | | + | | ::: | %%Pixy2Mode.LINE_MODE_WHITE_LINE%% | |
| **Returns:** ^^ | | **Returns:** ^^ | ||
| None ^^ | | None ^^ | ||
| **Example:** ^^ | | **Example:** ^^ | ||
| <code> | | <code> | ||
- | from pixy2 import Pixy2, Pixy2Mode | + | from pixycamev3.pixy2 import Pixy2, Pixy2Mode |
pixy2 = Pixy2(port=1, i2c_address=0x54) | pixy2 = Pixy2(port=1, i2c_address=0x54) | ||
Line 194: | Line 245: | ||
</code> ^^ | </code> ^^ | ||
- | ^ get_blocks(mode) ^^ | + | ^ %%get_blocks(mode)%% ^^ |
| **Description:** ^^ | | **Description:** ^^ | ||
| Gets all detected blocks in the most recent frame. ^^ | | Gets all detected blocks in the most recent frame. ^^ | ||
Line 202: | Line 253: | ||
| ::: | signature 1, then sigmap=1. If you are interested inbock data from | | | ::: | signature 1, then sigmap=1. If you are interested inbock data from | | ||
| ::: | signatures 1 and 2, then sigmap=3 (1+2). | | | ::: | signatures 1 and 2, then sigmap=3 (1+2). | | ||
- | | max_blocks | The maximum number of blocks you wish to receive. | | + | | %%max_blocks%% | The maximum number of blocks you wish to receive. | |
| **Returns:** ^^ | | **Returns:** ^^ | ||
- | | nr_blocks | Number of detected blocks | | + | | %%nr_blocks%% | Number of detected blocks | |
- | | blocks | List of Block objects (length = nr_blocks): ^^ | + | | blocks | List of Block objects (length = %%nr_blocks%%): | |
| sig | Signature or color code number | | | sig | Signature or color code number | | ||
- | | x_center | X location of the center of the block | | + | | %%x_center%% | X location of the center of the block | |
- | | y_center | Y location of the center of the block | | + | | %%y_center%% | Y location of the center of the block | |
| width | Width of the block | | | width | Width of the block | | ||
| height | Height of the block | | | height | Height of the block | | ||
| angle | Angle of color code in degrees | | | angle | Angle of color code in degrees | | ||
- | | tracking_index | Tracking index of the block | | + | | %%tracking_index%% | Tracking index of the block | |
| age | The number of frames the block has been tracked | | | age | The number of frames the block has been tracked | | ||
| **Example:** ^^ | | **Example:** ^^ | ||
| <code> | | <code> | ||
- | from pixy2 import Pixy2 | + | from pixycamev3.pixy2 import Pixy2 |
pixy2 = Pixy2(port=1, i2c_address=0x54) | pixy2 = Pixy2(port=1, i2c_address=0x54) | ||
Line 233: | Line 284: | ||
- | ^ get_line_tracking_data() ^^ | + | ^ %%get_line_tracking_data()%% ^^ |
| **Description:** ^^ | | **Description:** ^^ | ||
| Get linetracking data (MainFeatures) in the most recent frame. ^^ | | Get linetracking data (MainFeatures) in the most recent frame. ^^ | ||
Line 241: | Line 292: | ||
| MainFeatures object: ^^ | | MainFeatures object: ^^ | ||
| error | Data error when value True | | | error | Data error when value True | | ||
- | | length_of_payload | Number of bytes in payload | | + | | %%length_of_payload%% | Number of bytes in payload | |
- | | number_of_vectors | Number of vectors detected | | + | | %%number_of_vectors%% | Number of vectors detected | |
- | | number_of_intersections | Number of intersections detected | | + | | %%number_of_intersections%% | Number of intersections detected | |
- | | number_of_barcodes | Number of barcodes detected | | + | | %%number_of_barcodes%% | Number of barcodes detected | |
| vectors | List with Vector objects (length number_of_vectors) | | | vectors | List with Vector objects (length number_of_vectors) | | ||
| intersections | List with Intersection objects (length number_of_intersections) | | | intersections | List with Intersection objects (length number_of_intersections) | | ||
Line 255: | Line 306: | ||
| y1 | Y location endpoint vector | | | y1 | Y location endpoint vector | | ||
| index | Index of vector in array | | | index | Index of vector in array | | ||
- | | flags | <TODO: ??> | | + | | flags | Internal state, used for testing/debugging | |
| ^^ | | ^^ | ||
| Intersection object: ^^ | | Intersection object: ^^ | ||
| x | X location of intersection | | | x | X location of intersection | | ||
| y | Y location of intersection | | | y | Y location of intersection | | ||
- | | nr_of_branches | Number of branches starting at this intersection | | + | | %%nr_of_branches%% | Number of branches starting at this intersection | |
| branches | Array with Branch objects (length number_of_branches) | | | branches | Array with Branch objects (length number_of_branches) | | ||
| ^^ | | ^^ | ||
Line 266: | Line 317: | ||
| x | X location center of barcode | | | x | X location center of barcode | | ||
| y | Y location center of barcode | | | y | Y location center of barcode | | ||
- | | flags | <TODO: ??> | | + | | flags | Internal state, used for testing/debugging | |
| code | Number of barcode (see Pixy2 wiki) | | | code | Number of barcode (see Pixy2 wiki) | | ||
| ^^ | | ^^ | ||
Line 272: | Line 323: | ||
| index | Index in array | | | index | Index in array | | ||
| angle | Angle of branch | | | angle | Angle of branch | | ||
- | | angle_byte1 | Byte1 of angle | | + | | %%angle_byte1%% | Byte1 of angle | |
- | | angle_byte2 | Byte2 of angle | | + | | %%angle_byte2%% | Byte2 of angle | |
| **Example:** ^^ | | **Example:** ^^ | ||
| <code> | | <code> | ||
- | from pixy2 import Pixy2 | + | from pixycamev3.pixy2 import Pixy2 |
+ | |||
+ | pixy2 = Pixy2(port=1, i2c_address=0x54) | ||
# Detect barcodes and print their number | # Detect barcodes and print their number | ||
Line 286: | Line 339: | ||
</code> ^^ | </code> ^^ | ||
- | ==== Examples ==== | + | ^ %%set_next_turn(angle)%% ^^ |
+ | | **Description:** ^^ | ||
+ | | Set direction for turn at the next intersection. After this intersection ^^ | ||
+ | | Pixy2 will choose it's default turn again. ^^ | ||
+ | | **Parameters:** ^^ | ||
+ | | angle | Direction to choose at the next intersection (-180, 180 degrees) | | ||
+ | | **Returns:** ^^ | ||
+ | | None ^^ | ||
+ | | **Example:** ^^ | ||
+ | | <code> | ||
+ | from time import sleep | ||
+ | from pixycamev3.pixy2 import Pixy2 | ||
- | You'll find more practical sample code [[<TODO:link to repo|here]]. | + | pixy2 = Pixy2(port=1, i2c_address=0x54) |
+ | # Set next turn to 90 degrees | ||
+ | pixy2.set_next_turn(90) | ||
+ | </code> ^^ | ||
- | ===== Legal stuff ===== | + | ^ %%set_default_turn(angle)%% ^^ |
+ | | **Description:** ^^ | ||
+ | | Set default direction for all intersections. ^^ | ||
+ | | **Parameters:** ^^ | ||
+ | | angle | Default direction (-180, 180 degrees) | | ||
+ | | **Returns:** ^^ | ||
+ | | None ^^ | ||
+ | | **Example:** ^^ | ||
+ | | <code> | ||
+ | from time import sleep | ||
+ | from pixycamev3.pixy2 import Pixy2 | ||
- | <TODO: do we need this?> | + | pixy2 = Pixy2(port=1, i2c_address=0x54) |
- | LEGO and Mindstorms EV3 are registered trademarks of the LEGO Group. | + | |
- | BrickPi ... | + | # Set default turn to 0 degrees (straight on) |
+ | pixy2.set_default_turn(0) | ||
+ | </code> ^^ | ||
+ | |||
+ | ==== Examples ==== | ||
+ | |||
+ | You'll find more practical sample code in the | ||
+ | [[https://github.com/charmedlabs/pixycamev3|Github repository]]. | ||
+ | |||
+ | ===== Rasberry Pi ===== | ||
- | Pistorms ... | ||
<Work in progress> | <Work in progress> | ||
+ |