diff --git a/doc/api/start_pup.rst b/doc/api/start_pup.rst index 13064b7..46823c9 100644 --- a/doc/api/start_pup.rst +++ b/doc/api/start_pup.rst @@ -5,64 +5,63 @@ Powered Up Quick Start :height: 15 em :align: center -This page shows how you can install Pybricks on your hub and run your first -program. When you're ready, browse through the Pybricks Modules in the left -hand menu to modify the example program. +This page shows how you can install Pybricks on the BOOST Move Hub, the City +Hub, and the Technic Hub using the `Pybricks Code`_ interface. -.. note:: +You can reinstall the :ref:`original firmware ` at any time +using the official Powered Up app. - - **This is still in beta! Not everything may work as expected yet.** - - - We welcome your questions, feedback and bug reports on our `support page`_. - - - For now, sensors/motors are detected automatically only once. - So if you change the cables, you have to turn the hub off and on again. - You can turn it off by holding down the button for about 5 seconds. - -Installing Google Chrome +1. Requirements -------------------------------------- +* A BOOST Move Hub, City Hub, or Technic Hub. +* A Windows, Mac, Linux, or Android device. +* Bluetooth Low Energy (BLE). Make sure that Bluetooth is switched on. + +If you don't have BLE, the coding interface will inform you during the +installation step. In that case, you can try using a low-cost USB Bluetooth +Dongle thats support Bluetooth Low Energy. + +2. Installing a compatible browser +--------------------------------------------------- + Writing Pybricks programs requires a web browser with web Bluetooth -functionality. Currently, only Google Chrome supports this. -Download Google Chrome `from here`_. +functionality, such as: + + * `Google Chrome`_ + * `Microsoft Edge`_ + * Chromium If you use Linux, enable *Experimental Web Platform features* on -the ``chrome://flags/`` page. +the ``chrome://flags/`` page. On Windows and Mac, this is already enabled. -Installing the Pybricks firmware --------------------------------- +3. Installing the Pybricks firmware +----------------------------------- -Pybricks uses an improved firmware that can run autonomous programs. -Installing it is easy: +Before you begin, turn the hub off. The update works best with fresh batteries. +If you use the City Hub, you must unplug all motors and sensors. Follow these +steps: -1. Make sure you use fresh batteries. -2. Unplug all motors and sensors. -3. Follow the steps in the video below. +1. Go to `Pybricks Code`_. +2. Press and hold the green button, and wait for the light to start blinking. +3. While you hold it, click the firmware update button. +4. Select the ``LEGO Bootloader`` and click *Pair*. +5. Wait until the light goes off and until it blinks red/green/blue again. +6. You may now release the button and wait for the installation to finish. + +These steps are summarized in this video: .. raw:: html -
+

-If you prefer written instructions, follow these instead: - - Make sure you use fresh batteries. - - Unplug all motors and sensors. - - Make sure the hub is off. - - Press and hold the green button. - - Wait for the light to blink, but keep holding the button. - - On the Pybricks Code page, click the firmware update button. - - Select the ``LEGO Bootloader`` and click *Pair*. - - The light should change to a red/green/blue sequence. - - You can now release the button. - - Wait for the update to finish, indicated by a blinking blue light. - - If you use the recommended browser, this will take about 90 seconds. - -Running programs +4. Running programs -------------------------------- Once the firmware is installed, you can start coding! Use the *Bluetooth* -button to search for and connect to your *Pybricks Hub*. Then press run to +button to connect to your *Pybricks Hub*. Then press run to start your program. .. figure:: ../api/images/pybrickscode.png @@ -96,14 +95,54 @@ To get started, just copy and paste this snippet:: # Wait briefly, then repeat wait(10) +5. Next steps +----------------------------------------- -Restoring the LEGO Firmware ---------------------------- +Now that you've learned how to install Pybricks and run programs, check out +the steps below to make Pybricks coding even easier. We'll also show you how +you can restore the original firmware. -Pybricks uses the same update method as the LEGO apps; just with a different -firmware file. This means you can go back to the original firmware any time. -As shown in the video below, just put the hub in update mode and -connect using a LEGO app. +Saving a program on the hub +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Move Hub, City Hub, and Technic Hub do not have separate storage space +for user programs. This means your program is erased after it is done running. +Fortunately, you can still save one program on the hub, by including it in the +firmware. To do so: + +1. Open the settings tab with the ⚙ icon. +2. Activate the *Include current program* switch. +3. Update the firmware as you did before. Now, your current program will be + included. +4. Now can start and stop your program with the green button. + No connection required! +5. You can still download and run new programs with the run button as usual. + +This is a bit of a slow process to do each time. We recommend to +use the run button to run your code most of the time. When you are +happy with your final program, follow the steps above to save it on the hub. + +Using Pybricks offline +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Instead of working in your browser, you can install Pybricks locally: + +1. Open the settings tab with the ⚙ icon. +2. Click on *Install as App* and follow the on-screen instructions. + +To uninstall, click the ⋮ menu in the top and +click *Uninstall*. Note that this only removes the app from your computer. +To restore the original firmware on the hub, see the next section. + +.. _restoring: + +Restoring the original firmware +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pybricks uses the same update procedure as the LEGO apps. The only difference +is which firmware file we upload. This means you can go back to the original +firmware any time. As shown in the video below, just put the hub in update mode +and connect using a LEGO app. .. raw:: html @@ -113,39 +152,23 @@ This video shows the Powered Up app in *create* mode. It has firmware for all hubs. As usual, you may need to restart the app to detect the hub. If it fails, try again with fresh batteries. -Saving a program permanently (BETA) ------------------------------------ -.. note:: +Installing the latest build +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. warning:: - This functionality is in beta. It is currently only recommended for - advanced users. In the long run, we'll make this easy to do with - the online editor. + This section is only intended for developers who want to try the + latest features. Some features may not work when you do this. To revert + to a stable version, just install the firmware as you normally would. -When you run a program the normal way, it is deleted as soon as it's done. -That's because Powered Up hubs don't have a file system to store programs. -Fortunately, you can still save a script on the hub by including it -in the firmware. +Pybricks Code automatically provides the latest stable and tested firmware. +To get a more recent version, log in to GitHub and go to our `latest builds`_. +Click on the desired build and go to `Artifacts`. +Download the firmware ZIP archive for your hub. To install it, drag this file +*onto* the firmware update button in Pybricks Code. The update now proceeds as +usual. -Of course, this is a bit slow to do every time. We recommend the -using the standard procedure most of the time. -When you're happy with your final program, you can save it permanently as -described below. To change the program, just repeat these steps: - -1. Sign in to GitHub. -2. Go to our `GitHub builds`_. -3. Click on the build you want. This is usually the one at the top. -4. Then scroll down to `Artifacts`. -5. Download the firmware for your hub. The firmware is a ZIP archive - containing the basic firmware and one ``main.py`` script. -6. Modify the ``main.py`` file as you like. -7. Drag your modified ZIP file *onto* the firmware update button of the - online editor. -8. The update now proceeds as usual. - -*Once installed, you can start that program with the green button. -No connection required!* - -.. _GitHub builds: https://github.com/pybricks/pybricks-micropython/actions?query=is%3Asuccess+branch%3Amaster+workflow%3ABuild +.. _latest builds: https://github.com/pybricks/pybricks-micropython/actions?query=is%3Asuccess+branch%3Amaster+workflow%3ABuild .. _support page: https://github.com/pybricks/support/issues/ .. _Pybricks Code: http://code.pybricks.com/ -.. _from here: https://www.google.com/chrome/ +.. _Google Chrome: https://www.google.com/chrome/ +.. _Microsoft Edge: https://www.microsoft.com/en-us/edge