diff --git a/source/_images/devicebrowser.svg b/source/_images/devicebrowser.svg new file mode 100644 index 0000000..8f8b958 --- /dev/null +++ b/source/_images/devicebrowser.svg @@ -0,0 +1,263 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + Open devices + + 1 + + + + Choose device type + + 2 + + + + Watch values + + 3 + + diff --git a/source/_images/devicebrowser0.png b/source/_images/devicebrowser0.png new file mode 100644 index 0000000..bab1000 Binary files /dev/null and b/source/_images/devicebrowser0.png differ diff --git a/source/_images/devicebrowser1.png b/source/_images/devicebrowser1.png new file mode 100644 index 0000000..3bb7ad7 Binary files /dev/null and b/source/_images/devicebrowser1.png differ diff --git a/source/_images/devicebrowser2.png b/source/_images/devicebrowser2.png new file mode 100644 index 0000000..47d661e Binary files /dev/null and b/source/_images/devicebrowser2.png differ diff --git a/source/_images/devicebrowser3.png b/source/_images/devicebrowser3.png new file mode 100644 index 0000000..c3dc61e Binary files /dev/null and b/source/_images/devicebrowser3.png differ diff --git a/source/_images/devicebrowser4.png b/source/_images/devicebrowser4.png new file mode 100644 index 0000000..859c140 Binary files /dev/null and b/source/_images/devicebrowser4.png differ diff --git a/source/_images/etcher.svg b/source/_images/etcher.svg index 40deb0d..25174c2 100644 --- a/source/_images/etcher.svg +++ b/source/_images/etcher.svg @@ -25,7 +25,7 @@ image/svg+xml - + @@ -40,26 +40,26 @@ guidetolerance="10" inkscape:pageopacity="0" inkscape:pageshadow="2" - inkscape:window-width="1853" - inkscape:window-height="1016" + inkscape:window-width="1920" + inkscape:window-height="1043" id="namedview4" showgrid="false" inkscape:zoom="0.89655172" - inkscape:cx="389.22745" - inkscape:cy="256.08603" - inkscape:window-x="67" - inkscape:window-y="27" + inkscape:cx="6.4836564" + inkscape:cy="285.3705" + inkscape:window-x="1920" + inkscape:window-y="0" inkscape:window-maximized="1" - inkscape:current-layer="svg2" /> + inkscape:current-layer="g913" /> + preserveAspectRatio="none" + id="image10" + x="0" + y="0" /> 1 + x="136.02188" + y="-240.92017" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:'Roboto Slab';-inkscape-font-specification:'Roboto Slab';fill:#404140;fill-opacity:1;stroke-width:0.60486054">a 3 + x="310.07251" + y="21.838886" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:'Roboto Slab';-inkscape-font-specification:'Roboto Slab';fill:#404140;fill-opacity:1;stroke-width:0.60486054">c 2 + sodipodi:role="line">b diff --git a/source/_images/manualrun.svg b/source/_images/manualrun.svg index 94953e7..3de3764 100644 --- a/source/_images/manualrun.svg +++ b/source/_images/manualrun.svg @@ -26,17 +26,17 @@ borderopacity="1.0" inkscape:pageopacity="0.0" inkscape:pageshadow="2" - inkscape:zoom="0.98994949" - inkscape:cx="468.22212" - inkscape:cy="187.09034" + inkscape:zoom="1.4" + inkscape:cx="401.05456" + inkscape:cy="176.09284" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="false" units="px" - inkscape:window-width="1853" - inkscape:window-height="1016" - inkscape:window-x="67" - inkscape:window-y="27" + inkscape:window-width="1920" + inkscape:window-height="1043" + inkscape:window-x="1920" + inkscape:window-y="0" inkscape:window-maximized="1" inkscape:snap-global="false" /> - + + id="image836" + preserveAspectRatio="none" + height="24.353558" + width="33.866669" + style="stroke-width:0.88999999" /> + preserveAspectRatio="none" + height="24.353558" + width="33.866669" + style="stroke-width:0.88999999" /> + preserveAspectRatio="none" + height="24.353558" + width="33.866669" + style="stroke-width:0.88999999" /> 3 + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + Main menu + + 1 + + + + Power Off + + 3 + + + + Press back button + + 2 + + diff --git a/source/_images/onoff0.png b/source/_images/onoff0.png new file mode 100644 index 0000000..5eb4791 Binary files /dev/null and b/source/_images/onoff0.png differ diff --git a/source/index.rst b/source/index.rst index 28294b8..6a6cc2c 100644 --- a/source/index.rst +++ b/source/index.rst @@ -8,15 +8,16 @@ Using Python with LEGO\ :sup:`®` MINDSTORMS\ :sup:`®` EV3 .. toctree:: :maxdepth: 1 - :caption: Getting started: + :caption: Getting Started + :hidden: startinstall startrun - .. toctree:: :maxdepth: 1 - :caption: Pybricks Modules: + :caption: Pybricks Modules + :hidden: ev3brick ev3devices @@ -25,19 +26,33 @@ Using Python with LEGO\ :sup:`®` MINDSTORMS\ :sup:`®` EV3 .. toctree:: :maxdepth: 1 - :caption: Engineering essentials: + :caption: Engineering Essentials + :hidden: signaltypes .. motorcontrol - - .. toctree:: :maxdepth: 1 - :caption: Examples: + :caption: Demo Programs + :hidden: examples/color_sorter examples/robot_arm_h25 +Getting started +----------------------------------------------------------- + +This guide shows you how to get started writing MicroPython programs for your LEGO® MINDSTORMS® EV3 robots. You'll learn to do so in two steps: + +- :doc:`Installation `: First you'll prepare your computer and your EV3 by collecting and installing the required tools. You'll also learn how to turn the EV3 brick on and off and to navigate the menu on the screen. +- :doc:`Creating and running programs `: Next, you'll learn how to create a program and download it to the EV3 brick. You'll also learn how to start that program, with or without a computer nearby. + +Pybricks Modules and Demo Programs +----------------------------------------------------------- + +After you've run the first demo program, you'll be ready to try out the example programs, or even invent your own programs. Follow the menu on the left to learn how to use the EV3 brick, EV3 motors, and EV3 sensors effectively in your programs. + + diff --git a/source/startinstall.rst b/source/startinstall.rst index d5481f8..6c02bda 100644 --- a/source/startinstall.rst +++ b/source/startinstall.rst @@ -1,71 +1,121 @@ Installation =================== -This page shows how you prepare your computer and the EV3 brick for writing and running Python programs. The final configuration is shown in the figure below. - - -.. figure:: images/overview.png - -.. Caption - What do you need? ----------------------------------------------------------- -To get started writing Python programs for your robot, you need the following items: +The typical configuration for developing a MicroPython program for your EV3 robot is shown in the figure below. The steps on this page show you how you can make this work. -- a Windows 10 or Mac OS computer -- a micro SD card and card reader -- a mini-USB cable (comes with the EV3 kit) -You'll need internet access to complete the steps on this page. While programming your robots afterwards, internet access is not required. +.. figure:: images/overview.png + :scale: 75 % + :alt: overview + :align: center + Overview of the programming workflow + +To get started, you'll need the following items: + +- A Windows 10 or Mac OS computer. +- A micro SD card. You'll need a card with a minimum size of 4GB and a maximum size of 32GB, also known as microSDHC cards. We recommend cards with Application Performance Class A1. +- A micro SD card slot or card reader. +- A mini-USB cable. The EV3 kit includes such a cable. + +You'll need internet access to complete the steps on this page. When programming your robots afterwards, internet access is not required. Preparing your computer ----------------------------------------------------------- +You'll write your MicroPython programs using Visual Studio Code. Follow the steps below to download, install, and configure this program: + +1. Download and install Visual Studio Code from `here `_. +2. Launch Visual Studio Code. +3. Install and activate the required extension as shown below: -You will be writing your Python programs using Visual Studio Code. You can download, install, and configure this program using the steps below. +.. figure:: images/store.png + :alt: store + :align: center -1. Download, install, and open `Visual Studio Code `_. -2. Install the EV3 extension as shown below: - -.. image:: images/store.png + Installing the extension from the Visual Studio Code marketplace .. warning:: The all-in-one extension is not yet available in the Visual Studio Code marketplace. - Please install the **two** extensions manually as shown: + Please install the **two** extension files manually as shown: .. image:: images/vsix.png -Preparing the SD Card +.. _prepsdcard: + +Preparing the micro SD Card ----------------------------------------------------------- -You will now follow a series of steps to download and install the EV3 Python firmware onto your micro SD card. +You will now follow a series of steps to download and install the EV3 Python firmware onto your micro SD card. This "firmware" consists of `ev3dev `_, along with all the tools to run Pybricks MicroPython programs. - -1. Download the `EV3 Python firmware <.>`_ and save it in a convenient location. Do *not* unzip the file. -2. Download and install `Etcher `_. This is the program for installing the firmware file on your micro SD card. +1. Download the `EV3 Python firmware <.>`_ (approximately 360 MB) and save it in a convenient location. Do **not** open or unzip the file. +2. Download and install an micro SD card flashing tool such as `Etcher `_. 3. Insert the micro SD card into your computer or card reader. -4. Launch the etcher program and follow the steps on your screen to install the firmware file you have just downloaded. Do not remove the card until the installation process is complete. -5. Turn the EV3 brick off if it is currently on. -6. Put the micro SD card in the SD card slot of the EV3 brick. +4. Launch the flashing tool and follow the steps on your screen to install the firmware file you have just downloaded. If you use Etcher, you can follow the instructions in the diagram below: -.. image:: images/etcher.png + a. Select the firmware file you have just downloaded. + b. Select your micro SD card. Make sure that the device and size correspond to your micro SD card. + c. Start the flashing process. This may take several minutes. Do not remove the card until the installation process is complete. + +.. figure:: images/etcher.png + :scale: 75 % + :alt: etcher + :align: center + + Using Etcher to flash the firmware to the micro SD card Using the EV3 brick ----------------------------------------------------------- -.. image:: images/sd.png +Make sure the EV3 brick is turned off, and insert the micro SD card you just prepared into the SD card slot on the EV3, as shown below. + +.. figure:: images/sd.png + :scale: 60 % + :alt: sd + :align: center + + Inserting the finished micro SD card into the EV3 brick + Turning the EV3 brick on and off ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To turn the EV3 on, press the dark gray center button to turn the EV3 brick on. The boot process may take several minutes. -Using the file browser +To turn it off, use the back button (the button just below the screen) to go to the main menu. Once at the main menu, press the back button to show the shutdown menu. Select *Power Off* to turn the brick off, or press the back button again to cancel. + +.. figure:: images/onoff.png + :scale: 80 % + :alt: devicebrowser + :align: center + + Turning the EV3 brick off + + +Going back to the original firmware ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +You can go back to the LEGO® firmware and your LEGO® programs at any time. To do so: + +1. Turn the EV3 off as shown above. +2. Wait for the screen and light to turn off. +3. Remove the micro SD card. +4. Turn the EV3 on. + Viewing motor and sensor values ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When you're not running a program, you can view motor and sensor values using the device browser, as shown below. + +.. figure:: images/devicebrowser.png + :scale: 80 % + :alt: devicebrowser + :align: center + + Viewing motor and sensor values