Skip to content

Commit

Permalink
doc/start_ev3: add upgrade guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@laurensvalk
laurensvalk committed May 18, 2020
1 parent b26d1e7 commit d744d4a
Show file tree
Hide file tree
Showing 2 changed files with 123 additions and 0 deletions.
2 changes: 2 additions & 0 deletions doc/api/start_ev3.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@ EV3 Quick Start
.. include:: start_ev3_run.inc

.. include:: start_ev3_linux.inc

.. include:: start_ev3_upgrade.inc
121 changes: 121 additions & 0 deletions doc/api/start_ev3_upgrade.inc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
Upgrading from v1.0 to v2.0
===============================

*EV3 MicroPython version 2.0 was released on May 18, 2020.*

This section is for users who have previously used LEGO MINDSTORMS EV3
MicroPython v1.0. We'll explain what's changed and how you can upgrade to
benefit from the latest improvements.

If you are a new user and you just got started using version 2.0, you may skip
this section.

What is new in v2.0?
-----------------------------------------

.. todo::

To do

Upgrading the microSD Card
-----------------------------------------

To upgrade, download the latest microSD card file and install it using the
standard :ref:`instructions <prepsdcard>`.

Note that this will erase all your existing files on the SD Card. Before you
upgrade, make sure that you still have all your projects on your computer.
If not, you can upload files back to your computer using
:ref:`these instructions <managefiles>`.

As with any software update, *be careful about when you update*. For example,
if you developed your code using version v1.0 and you are halfway into your
robotics competition season, you want to stick with v1.0 for now.


Upgrading your existing programs
-----------------------------------------

All originally documented features in v1.0 will still work after you upgrade.
This means that most programs originally made for v1.0 will work with the v2.0
microSD card image without any changes.

To try this, simply download and run your original code as you did before.

However, it is recommended that you upgrade both the microSD card and your
programs at the same time to ensure everything works as expected.

New way to use the EV3 Brick
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Version 2.0 introduces the :class:`EV3Brick() <pybricks.hubs.EV3Brick>` class.
You can use it instead of the old ``ev3brick`` module.

This class improves the speed and reliability of the EV3 screen and the EV3
speaker. It also adds functionality like speech and drawing shapes. The default
font size is also bigger to make it easier to read text on the screen.

You can use
the following table as a starting point to upgrade your scripts.

+-----------------+--------------------------------------------------+----------------------------------------------------+
| Action | v1.0 | v2.0 |
+=================+==================================================+====================================================+
| | Initialize | :: | :: |
| | your EV3 | | |
| | from pybricks import ev3brick as brick | from pybricks.hubs import EV3Brick |
| | | |
| | | ev3 = EV3Brick() |
+-----------------+--------------------------------------------------+----------------------------------------------------+
| | Light | :: | :: |
| | | |
| | brick.light(Color.RED) | ev3.light.on(Color.RED) |
+-----------------+--------------------------------------------------+----------------------------------------------------+
| | Read | :: | :: |
| | buttons | | |
| | if Button.LEFT in brick.buttons(): | if Button.LEFT in ev3.buttons.pressed(): |
| | print("Left is pressed.") | print("Left is pressed.") |
+-----------------+--------------------------------------------------+----------------------------------------------------+
| | Play a | :: | :: |
| | beep | | |
| | brick.sound.beep() | ev3.speaker.beep() |
+-----------------+--------------------------------------------------+----------------------------------------------------+
| | Play a | :: | :: |
| | file | | |
| | brick.sound.file(SoundFile.HELLO) | ev3.speaker.play_file(SoundFile.HELLO) |
+-----------------+--------------------------------------------------+----------------------------------------------------+
| | Speech | | :: |
| | | |
| | | ev3.speaker.say("I can say anything!") |
+-----------------+--------------------------------------------------+----------------------------------------------------+
| | Play | | :: |
| | notes | | |
| | | |
| | | ev3.speaker.play_notes(['C4/4', 'G4/4']) |
+-----------------+--------------------------------------------------+----------------------------------------------------+
| | Write text | :: | :: |
| | on the screen | | |
| | brick.display.text("Hello!", (50, 60)) | ev3.screen.draw_text(50, 60, "Hello!") |

This comment has been minimized.

Sign in to view

Copy link
@dlech

dlech May 18, 2020

Member

FYI, it looks like you copied this before I was done making changes in pybricks/lego-vscode-ev3-micropython#31 (comment).

This comment has been minimized.

Sign in to view

Copy link
@laurensvalk

laurensvalk May 19, 2020

Author Member

Thanks! I'll update.
+-----------------+--------------------------------------------------+----------------------------------------------------+
| | Display an | :: | :: |
| | image on | | |
| | the screen | brick.display.image(ImageFile.QUESTION_MARK) | ev3.screen.load_image(ImageFile.Question_MARK) |
+-----------------+--------------------------------------------------+----------------------------------------------------+
| | Write text | | :: |
| | and scroll | | |
| | automatically | | ev3.screen.print("Hello") |
+-----------------+--------------------------------------------------+----------------------------------------------------+
| | Read | :: | :: |
| | Battery | | |
| | voltage | brick.battery.voltage() | ev3.battery.voltage() |
+-----------------+--------------------------------------------------+----------------------------------------------------+

See the :class:`EV3Brick() <pybricks.hubs.EV3Brick>` class documentation for
complete details of all methods and arguments.

Other internal changes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. todo::

To do

0 comments on commit d744d4a

Please sign in to comment.