diff --git a/doc/LICENSE b/doc/LICENSE new file mode 100644 index 0000000..1d15cfb --- /dev/null +++ b/doc/LICENSE @@ -0,0 +1,23 @@ +MIT License + +Copyright (c) 2018-2019 Laurens Valk +Copyright (c) 2018-2019 David Lechner +Copyright (c) 2019 LEGO System A/S + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..a81e974 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,21 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = -W +SPHINXBUILD = sphinx-build +SPHINXPROJ = Pybricks +SOURCEDIR = ev3dev +BUILDDIR = "$(SOURCEDIR)"/build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(MAKE) -C "$(SOURCEDIR)"/_images `[ "$@" = "clean" ] && echo clean || echo all` + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/common/_images/Makefile b/doc/common/_images/Makefile new file mode 100755 index 0000000..cf15c72 --- /dev/null +++ b/doc/common/_images/Makefile @@ -0,0 +1,15 @@ + +SRC_DIR = . +OUT_DIR = ../images + +SVG := $(wildcard $(SRC_DIR)/*.svg) +PNG := $(patsubst $(SRC_DIR)/%.svg,$(OUT_DIR)/%.png,$(SVG)) +DIR := ${CURDIR} + +all: $(PNG) + +clean: + rm -f $(PNG) + +$(OUT_DIR)/%.png: $(SRC_DIR)/%.svg + inkscape --file=$(DIR)/$< --export-area-drawing --export-png=$(DIR)/$@ diff --git a/doc/common/_static/css/theme_overrides.css b/doc/common/_static/css/theme_overrides.css new file mode 100644 index 0000000..027694d --- /dev/null +++ b/doc/common/_static/css/theme_overrides.css @@ -0,0 +1,11 @@ +div.disclaimer { + margin-top: 12px; + font-size: 10px; + font-style: italic; +} +div.figure p.caption { + padding-top: 0.8em; +} +span.caption-number:after { + content: ": "; + } diff --git a/doc/common/_templates/footer.html b/doc/common/_templates/footer.html new file mode 100644 index 0000000..9796df6 --- /dev/null +++ b/doc/common/_templates/footer.html @@ -0,0 +1,5 @@ +{% extends '!footer.html' %} + +{% block extrafooter %} +
{{ disclaimer }}
+{% endblock %} diff --git a/doc/common/conf.py b/doc/common/conf.py new file mode 100644 index 0000000..bcea33c --- /dev/null +++ b/doc/common/conf.py @@ -0,0 +1,249 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Pybricks documentation build configuration file, created by +# sphinx-quickstart on Thu Sep 6 15:31:12 2018. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../../lib/fake-pybricks/pybricks')) + +import _version # noqa E402 + +# ON_RTD is whether we are on readthedocs.org +# this line of code grabbed from docs.readthedocs.org +ON_RTD = os.environ.get('READTHEDOCS', None) == 'True' + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.todo', + 'sphinx.ext.mathjax', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['../common/_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'pybricks-micropython' +copyright = '2018-2019 The Pybricks MicroPython Authors' +author = '' + +_TITLE = 'Pybricks Modules and Examples' +_DISCLAIMER = 'LEGO, the LEGO logo, MINDSTORMS and the MINDSTORMS EV3 logo are trademarks and/or copyrights of the LEGO Group.' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = _version.get_versions()['version'] +# The full version, including alpha/beta/rc tags. +release = version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [ + 'motorcontrol.rst', +] + +# TODO: remove this when pages above are added back in +suppress_warnings = ['ref.ref'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + +# Figure numbering +numfig = True +numfig_format = { + 'figure': 'Figure %s', + 'table': 'Table %s', + 'code-block': 'Listing %s', + 'section': 'Section %s' +} + +# -- Autodoc options ------------------------------------------------------ + +autodoc_member_order = 'bysource' +autodoc_default_flags = ['members', 'undoc-members'] +autoclass_content = 'both' # This ensures init arguments are not ignored but added to class docstring. +add_module_names = False # Hide module name + +# -- Options for HTML output ---------------------------------------------- + +if ON_RTD: + html_theme = 'default' + html_context = { + 'css_files': [ + 'https://media.readthedocs.org/css/sphinx_rtd_theme.css', + 'https://media.readthedocs.org/css/readthedocs-doc-embed.css', + '_static/css/theme_overrides.css', + ], + 'disclaimer': _DISCLAIMER, + } +else: + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + html_context = { + 'css_files': [ + '_static/css/theme_overrides.css', + ], + 'disclaimer': _DISCLAIMER, + } + +html_logo = '../common/images/pybricks-logo-small.png' + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +# html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = { + 'style_external_links': True, +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['../common/_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Pybricksdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + 'preamble': r''' + \makeatletter + \fancypagestyle{normal}{ + \fancyhf{} + \fancyfoot[R]{{\py@HeaderFamily\thepage}} + \fancyfoot[C]{\raisebox{-7mm}{\tiny %(disclaimer)s}} + \fancyhead[L]{{\py@HeaderFamily \@title}} + \fancyhead[R]{{\py@HeaderFamily \py@release}} + \renewcommand{\headrulewidth}{0.4pt} + \renewcommand{\footrulewidth}{0.4pt} + } + \fancypagestyle{plain}{ + \fancyhf{} + \fancyfoot[R]{{\py@HeaderFamily\thepage}} + \fancyfoot[C]{\raisebox{-7mm}{\tiny %(disclaimer)s}} + \renewcommand{\headrulewidth}{0.4pt} + \renewcommand{\footrulewidth}{0.4pt} + } + \makeatother + ''' % { + 'disclaimer': ' '.join((_DISCLAIMER, '©', copyright)), + }, + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', + 'extraclassoptions': 'openany,oneside', + + 'releasename': 'Version', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, ''.join([project, '-v', version, '.tex']), _TITLE, author, 'manual'), +] + +latex_logo = '../common/images/pybricks-logo-large.png' + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'pybricks', 'Pybricks Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Pybricks', 'Pybricks Documentation', + author, 'Pybricks', 'One line description of project.', + 'Miscellaneous'), +] diff --git a/doc/common/images/.gitignore b/doc/common/images/.gitignore new file mode 100644 index 0000000..8ab8387 --- /dev/null +++ b/doc/common/images/.gitignore @@ -0,0 +1,3 @@ +*.png +!pybricks-logo-large.png +!pybricks-logo-small.png diff --git a/doc/common/images/pybricks-logo-large.png b/doc/common/images/pybricks-logo-large.png new file mode 100644 index 0000000..ace5c2b Binary files /dev/null and b/doc/common/images/pybricks-logo-large.png differ diff --git a/doc/common/images/pybricks-logo-small.png b/doc/common/images/pybricks-logo-small.png new file mode 100644 index 0000000..85b8758 Binary files /dev/null and b/doc/common/images/pybricks-logo-small.png differ diff --git a/doc/common/robotics.rst b/doc/common/robotics.rst new file mode 100644 index 0000000..fd7023b --- /dev/null +++ b/doc/common/robotics.rst @@ -0,0 +1,4 @@ +:mod:`robotics` -- Robotics module +=========================================== + +.. automodule:: robotics diff --git a/doc/common/signaltypes.rst b/doc/common/signaltypes.rst new file mode 100644 index 0000000..2af0cf4 --- /dev/null +++ b/doc/common/signaltypes.rst @@ -0,0 +1,129 @@ +Signals and Units +================= + +Many commands allow you to specify arguments in terms of well-known physical quantities. This page gives an overview of each quantity and its unit. + +.. _time: + +time: ms +--------- +All time and duration values are measured in milliseconds (ms). + +For example, the duration of motion with :meth:`run_time <.ev3devices.Motor.run_time>`, the duration of :func:`wait <.tools.wait>`, or the time values returned by the :class:`StopWatch <.tools.StopWatch>` are specified in milliseconds. + +.. _angle: + +angle: deg +----------- +All angles are measured in degrees (deg). One full rotation corresponds to 360 degrees. + +For example, the angle values of a :meth:`Motor <.ev3devices.Motor.angle>` or the :meth:`GyroSensor <.ev3devices.GyroSensor.angle>` are expressed in degrees. + +.. _speed: + +rotational speed: deg/s +----------------------- + +Rotational speed, or *angular velocity* describes how fast something rotates, expressed as the number of degrees per second (deg/s). + +For example, the rotational speed values of a :meth:`Motor <.ev3devices.Motor.speed>` or the :meth:`GyroSensor <.ev3devices.GyroSensor.speed>` are expressed in degrees per second. + +While we recommend working with degrees per second in your programs, you can use the following table to convert between commonly used units. + ++-----------+-------+-----------+ +| | deg/s | rpm | ++-----------+-------+-----------+ +| 1 deg/s = | 1 | 1/6=0.167 | ++-----------+-------+-----------+ +| 1 rpm = | 6 | 1 | ++-----------+-------+-----------+ + +.. _distance: + +distance: mm +------------- +Distances are expressed in millimeters (mm) whenever possible. + +For example, the distance value of the :meth:`UltrasonicSensor <.ev3devices.UltrasonicSensor.distance>` is measured in millimeters. + +While we recommend working with millimeters in your programs, you can use the following table to convert between commonly used units. + ++---------+------+-----+--------+ +| | mm | cm | inch | ++---------+------+-----+--------+ +| 1 mm = | 1 | 0.1 | 0.0394 | ++---------+------+-----+--------+ +| 1 cm = | 10 | 1 | 0.394 | ++---------+------+-----+--------+ +| 1 inch =| 25.4 | 2.54| 1 | ++---------+------+-----+--------+ + +.. _dimension: + +dimension: mm +------------- +Dimensions are expressed in millimeters (mm) whenever possible, just like distances. + +For example, the diameter of a wheel is measured in millimeters. + + +.. _relativedistance: + +relative distance: % +--------------------- + +Some distance measurements do not provide an accurate value with a specific unit, but they range from very close (0%) to very far (100%). These are referred to as relative distances. + +For example, the distance value of the :meth:`InfraredSensor <.ev3devices.InfraredSensor.distance>` is a relative distance. + + + + +.. _travelspeed: + +speed: mm/s +------------ +Linear speeds are expressed as millimeters per second (mm/s). + +For example, the speed of a robotic vehicle is expressed in mm/s. + +.. _acceleration: + +rotational acceleration: deg/s/s +-------------------------------- +Rotational acceleration, or *angular acceleration* describes how fast the rotational speed changes. This is expressed as the change of the number of degrees per second, during one second (deg/s/s). This is also commonly written as :math:`deg/s^2`. + +For example, you can adjust the rotational acceleration setting of a :meth:`Motor <.ev3devices.Motor.set_run_settings>` to change how smoothly or how quickly it reaches the constant speed set point. + + +.. _percentage: + +percentage: % +-------------- +Some signals do not have specific units but range from a minimum (0%) to a maximum (100%). A specific type of percentages are :ref:`relative distances `. + +For example, the sound :meth:`volume <.ev3brick.sound.beep>` ranges from 0% to 100%. + +.. _frequency: + +frequency: Hz +-------------- +Sound frequencies are expressed in Hertz (Hz). + +For example, you can choose the frequency of a :meth:`beep <.ev3brick.sound.beep>` to change the pitch. + +.. _voltage: + +voltage: mV +-------------- +Voltages are expressed in millivolt (mV). + +For example, you can check the voltage of the :meth:`battery <.ev3brick.battery.voltage>`. + +.. _current: + +current: mA +-------------- +Electrical currents are expressed in milliampere (mA). + +For example, you can check the current supplied by the :meth:`battery <.ev3brick.battery.current>`. diff --git a/doc/common/tools.rst b/doc/common/tools.rst new file mode 100644 index 0000000..e1638f6 --- /dev/null +++ b/doc/common/tools.rst @@ -0,0 +1,11 @@ +:mod:`tools` -- Timing and Datalogging +====================================== + +.. automodule:: tools + :no-members: + + .. autofunction:: print + + .. autofunction:: wait + + .. autoclass:: StopWatch diff --git a/doc/ev3dev/_images/Makefile b/doc/ev3dev/_images/Makefile new file mode 100755 index 0000000..cf15c72 --- /dev/null +++ b/doc/ev3dev/_images/Makefile @@ -0,0 +1,15 @@ + +SRC_DIR = . +OUT_DIR = ../images + +SVG := $(wildcard $(SRC_DIR)/*.svg) +PNG := $(patsubst $(SRC_DIR)/%.svg,$(OUT_DIR)/%.png,$(SVG)) +DIR := ${CURDIR} + +all: $(PNG) + +clean: + rm -f $(PNG) + +$(OUT_DIR)/%.png: $(SRC_DIR)/%.svg + inkscape --file=$(DIR)/$< --export-area-drawing --export-png=$(DIR)/$@ diff --git a/doc/ev3dev/_images/connecting.png b/doc/ev3dev/_images/connecting.png new file mode 100644 index 0000000..00f84c3 Binary files /dev/null and b/doc/ev3dev/_images/connecting.png differ diff --git a/doc/ev3dev/_images/connecting.svg b/doc/ev3dev/_images/connecting.svg new file mode 100644 index 0000000..b95318d --- /dev/null +++ b/doc/ev3dev/_images/connecting.svg @@ -0,0 +1,428 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + Open file tab + + 1 + + + + + + + Open device browser + + 3 + + + + + Search for your EV3 Brick + + 4 + + + + + Select your EV3 Brick + + 5 + + + + Connect your EV3 Brick with the USB cable + 4 + + 2 + + + diff --git a/doc/ev3dev/_images/connectingsub1.png b/doc/ev3dev/_images/connectingsub1.png new file mode 100644 index 0000000..cb7dbb2 Binary files /dev/null and b/doc/ev3dev/_images/connectingsub1.png differ diff --git a/doc/ev3dev/_images/connectingsub2.png b/doc/ev3dev/_images/connectingsub2.png new file mode 100644 index 0000000..f84cb22 Binary files /dev/null and b/doc/ev3dev/_images/connectingsub2.png differ diff --git a/doc/ev3dev/_images/devicebrowser.svg b/doc/ev3dev/_images/devicebrowser.svg new file mode 100644 index 0000000..8f8b958 --- /dev/null +++ b/doc/ev3dev/_images/devicebrowser.svg @@ -0,0 +1,263 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + Open devices + + 1 + + + + Choose device type + + 2 + + + + Watch values + + 3 + + diff --git a/doc/ev3dev/_images/devicebrowser0.png b/doc/ev3dev/_images/devicebrowser0.png new file mode 100644 index 0000000..bab1000 Binary files /dev/null and b/doc/ev3dev/_images/devicebrowser0.png differ diff --git a/doc/ev3dev/_images/devicebrowser1.png b/doc/ev3dev/_images/devicebrowser1.png new file mode 100644 index 0000000..3bb7ad7 Binary files /dev/null and b/doc/ev3dev/_images/devicebrowser1.png differ diff --git a/doc/ev3dev/_images/devicebrowser2.png b/doc/ev3dev/_images/devicebrowser2.png new file mode 100644 index 0000000..47d661e Binary files /dev/null and b/doc/ev3dev/_images/devicebrowser2.png differ diff --git a/doc/ev3dev/_images/devicebrowser3.png b/doc/ev3dev/_images/devicebrowser3.png new file mode 100644 index 0000000..c3dc61e Binary files /dev/null and b/doc/ev3dev/_images/devicebrowser3.png differ diff --git a/doc/ev3dev/_images/devicebrowser4.png b/doc/ev3dev/_images/devicebrowser4.png new file mode 100644 index 0000000..859c140 Binary files /dev/null and b/doc/ev3dev/_images/devicebrowser4.png differ diff --git a/doc/ev3dev/_images/etcher.png b/doc/ev3dev/_images/etcher.png new file mode 100644 index 0000000..8361132 Binary files /dev/null and b/doc/ev3dev/_images/etcher.png differ diff --git a/doc/ev3dev/_images/etcher.svg b/doc/ev3dev/_images/etcher.svg new file mode 100644 index 0000000..25174c2 --- /dev/null +++ b/doc/ev3dev/_images/etcher.svg @@ -0,0 +1,197 @@ + + + + + + + + image/svg+xml + + + + + + + + + + Select image + + Select drive + + Flash! + + + a + + + + c + + + 4 + + b + + diff --git a/doc/ev3dev/_images/existingproject.png b/doc/ev3dev/_images/existingproject.png new file mode 100644 index 0000000..e04f2d9 Binary files /dev/null and b/doc/ev3dev/_images/existingproject.png differ diff --git a/doc/ev3dev/_images/existingproject.svg b/doc/ev3dev/_images/existingproject.svg new file mode 100644 index 0000000..9a9325b --- /dev/null +++ b/doc/ev3dev/_images/existingproject.svg @@ -0,0 +1,249 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + Open a previouslycreated project + + 2 + + + + File + + 1 + + + + + + Open a recentlyused project + diff --git a/doc/ev3dev/_images/files.png b/doc/ev3dev/_images/files.png new file mode 100644 index 0000000..0356de6 Binary files /dev/null and b/doc/ev3dev/_images/files.png differ diff --git a/doc/ev3dev/_images/files.svg b/doc/ev3dev/_images/files.svg new file mode 100644 index 0000000..81a8e81 --- /dev/null +++ b/doc/ev3dev/_images/files.svg @@ -0,0 +1,284 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + Project on your computer + + + + + Project on the EV3 Brick + + + + + + Right click + + + + Upload file back to your computer + + + + Delete file from the EV3 Brick + diff --git a/doc/ev3dev/_images/files1.png b/doc/ev3dev/_images/files1.png new file mode 100644 index 0000000..5b42257 Binary files /dev/null and b/doc/ev3dev/_images/files1.png differ diff --git a/doc/ev3dev/_images/firstprogram.svg b/doc/ev3dev/_images/firstprogram.svg new file mode 100644 index 0000000..0e2a389 --- /dev/null +++ b/doc/ev3dev/_images/firstprogram.svg @@ -0,0 +1,156 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + Large Motor + + + + + + Port B + + + diff --git a/doc/ev3dev/_images/firstprogram1.jpg b/doc/ev3dev/_images/firstprogram1.jpg new file mode 100644 index 0000000..e2b6b60 Binary files /dev/null and b/doc/ev3dev/_images/firstprogram1.jpg differ diff --git a/doc/ev3dev/_images/firstprogram2.png b/doc/ev3dev/_images/firstprogram2.png new file mode 100644 index 0000000..1d21cfa Binary files /dev/null and b/doc/ev3dev/_images/firstprogram2.png differ diff --git a/doc/ev3dev/_images/manualrun.svg b/doc/ev3dev/_images/manualrun.svg new file mode 100644 index 0000000..3de3764 --- /dev/null +++ b/doc/ev3dev/_images/manualrun.svg @@ -0,0 +1,308 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + Open file browser + + 1 + + + + Open project folder + + 2 + + + + Run your program + + 3 + + + + Go to previous folder + + 4 + + diff --git a/doc/ev3dev/_images/manualrun1.png b/doc/ev3dev/_images/manualrun1.png new file mode 100644 index 0000000..6843377 Binary files /dev/null and b/doc/ev3dev/_images/manualrun1.png differ diff --git a/doc/ev3dev/_images/manualrun2.png b/doc/ev3dev/_images/manualrun2.png new file mode 100644 index 0000000..5bba8c5 Binary files /dev/null and b/doc/ev3dev/_images/manualrun2.png differ diff --git a/doc/ev3dev/_images/manualrun3.png b/doc/ev3dev/_images/manualrun3.png new file mode 100644 index 0000000..8d9ef0d Binary files /dev/null and b/doc/ev3dev/_images/manualrun3.png differ diff --git a/doc/ev3dev/_images/newproject.png b/doc/ev3dev/_images/newproject.png new file mode 100644 index 0000000..e80dc6e Binary files /dev/null and b/doc/ev3dev/_images/newproject.png differ diff --git a/doc/ev3dev/_images/newproject.svg b/doc/ev3dev/_images/newproject.svg new file mode 100644 index 0000000..c789d81 --- /dev/null +++ b/doc/ev3dev/_images/newproject.svg @@ -0,0 +1,294 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + Choose a location for yourproject in the pop-up window + + 4 + + + + + Open Pybricks tab + + 1 + + + + Create new project + + 2 + + + + + Choose a project name and press enter + + 3 + + + getting_started + diff --git a/doc/ev3dev/_images/onoff.svg b/doc/ev3dev/_images/onoff.svg new file mode 100644 index 0000000..942e136 --- /dev/null +++ b/doc/ev3dev/_images/onoff.svg @@ -0,0 +1,247 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + Main menu + + 1 + + + + Power Off + + 3 + + + + Press back button + + 2 + + diff --git a/doc/ev3dev/_images/onoff0.png b/doc/ev3dev/_images/onoff0.png new file mode 100644 index 0000000..5eb4791 Binary files /dev/null and b/doc/ev3dev/_images/onoff0.png differ diff --git a/doc/ev3dev/_images/overview.jpg b/doc/ev3dev/_images/overview.jpg new file mode 100644 index 0000000..07be516 Binary files /dev/null and b/doc/ev3dev/_images/overview.jpg differ diff --git a/doc/ev3dev/_images/overview.svg b/doc/ev3dev/_images/overview.svg new file mode 100644 index 0000000..0059c3d --- /dev/null +++ b/doc/ev3dev/_images/overview.svg @@ -0,0 +1,251 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + Computer with Visual Studio Code + + + + + Download and run + + + MicroSD card withEV3 MicroPython image + + + + + Mini-USB cable + + + + + + + EV3 Brick + diff --git a/doc/ev3dev/_images/projectoverview.png b/doc/ev3dev/_images/projectoverview.png new file mode 100644 index 0000000..c62fbcf Binary files /dev/null and b/doc/ev3dev/_images/projectoverview.png differ diff --git a/doc/ev3dev/_images/projectoverview.svg b/doc/ev3dev/_images/projectoverview.svg new file mode 100644 index 0000000..c688e6a --- /dev/null +++ b/doc/ev3dev/_images/projectoverview.svg @@ -0,0 +1,212 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + Write your program + + 2 + + + + Open main.py + + 1 + + + + + + + diff --git a/doc/ev3dev/_images/projectstructure.svg b/doc/ev3dev/_images/projectstructure.svg new file mode 100644 index 0000000..b9aa69d --- /dev/null +++ b/doc/ev3dev/_images/projectstructure.svg @@ -0,0 +1,375 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Project folder + + + getting_started + + + main.py + + + my_module.py + + + picture.png + + + sound.wav + + This main program runs when you press start (or F5) + + Any other files can be used by main.py + + + + diff --git a/doc/ev3dev/_images/running.png b/doc/ev3dev/_images/running.png new file mode 100644 index 0000000..0a0d3bc Binary files /dev/null and b/doc/ev3dev/_images/running.png differ diff --git a/doc/ev3dev/_images/running.svg b/doc/ev3dev/_images/running.svg new file mode 100644 index 0000000..3a81679 --- /dev/null +++ b/doc/ev3dev/_images/running.svg @@ -0,0 +1,323 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + Output + + 3 + + + + + Debug (or press F5) + + 1 + + + + + Download and run + + 2 + + + + + Download and run + + 2 + + + + + Stop + + 4 + diff --git a/doc/ev3dev/_images/screen.png b/doc/ev3dev/_images/screen.png new file mode 100644 index 0000000..fbde8be Binary files /dev/null and b/doc/ev3dev/_images/screen.png differ diff --git a/doc/ev3dev/_images/sd.svg b/doc/ev3dev/_images/sd.svg new file mode 100644 index 0000000..5921096 --- /dev/null +++ b/doc/ev3dev/_images/sd.svg @@ -0,0 +1,242 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + Place the cardin the SD slot,text side up + + + + + + + You can add a tape wrapperto easily removethe card later + + + First, turn offthe EV3 Brick + diff --git a/doc/ev3dev/_images/sd1.jpg b/doc/ev3dev/_images/sd1.jpg new file mode 100644 index 0000000..92de0c8 Binary files /dev/null and b/doc/ev3dev/_images/sd1.jpg differ diff --git a/doc/ev3dev/_images/sd2.png b/doc/ev3dev/_images/sd2.png new file mode 100644 index 0000000..ad20789 Binary files /dev/null and b/doc/ev3dev/_images/sd2.png differ diff --git a/doc/ev3dev/_images/store.svg b/doc/ev3dev/_images/store.svg new file mode 100644 index 0000000..18cd0b7 --- /dev/null +++ b/doc/ev3dev/_images/store.svg @@ -0,0 +1,367 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + Open extensions tab + + 1 + + + + + Search + + 2 + + + + Install + 4 + + 3 + + Pybricks for LEGO MINDSTORMS EV3 + Create and run MicroPython scripts for EV3 + Pybricks + + + + Reload toactivate + 4 + + 4 + Pybricks + diff --git a/doc/ev3dev/_images/store0.png b/doc/ev3dev/_images/store0.png new file mode 100644 index 0000000..2f83ee7 Binary files /dev/null and b/doc/ev3dev/_images/store0.png differ diff --git a/doc/ev3dev/_images/store2.png b/doc/ev3dev/_images/store2.png new file mode 100644 index 0000000..d34f7b9 Binary files /dev/null and b/doc/ev3dev/_images/store2.png differ diff --git a/doc/ev3dev/_images/store3.png b/doc/ev3dev/_images/store3.png new file mode 100644 index 0000000..5512c9b Binary files /dev/null and b/doc/ev3dev/_images/store3.png differ diff --git a/doc/ev3dev/_images/vsix.png b/doc/ev3dev/_images/vsix.png new file mode 100644 index 0000000..4137d48 Binary files /dev/null and b/doc/ev3dev/_images/vsix.png differ diff --git a/doc/ev3dev/_images/vsix.svg b/doc/ev3dev/_images/vsix.svg new file mode 100644 index 0000000..55ad511 --- /dev/null +++ b/doc/ev3dev/_images/vsix.svg @@ -0,0 +1,266 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + More Actions + + 2 + + + + + Extensions + + 1 + + + + + Install from VSIX + + 3 + + + + diff --git a/doc/ev3dev/conf.py b/doc/ev3dev/conf.py new file mode 100644 index 0000000..a426e43 --- /dev/null +++ b/doc/ev3dev/conf.py @@ -0,0 +1,8 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Pybricks documentation build configuration file +# +import os +import sys +exec(open(os.path.abspath("../common/conf.py")).read()) diff --git a/doc/ev3dev/ev3brick.rst b/doc/ev3dev/ev3brick.rst new file mode 100644 index 0000000..3b374fe --- /dev/null +++ b/doc/ev3dev/ev3brick.rst @@ -0,0 +1,59 @@ +:mod:`ev3brick` -- The EV3 Programmable Brick +============================================= + +.. automodule:: ev3brick + :no-members: + + +Buttons +------- + +.. autofunction:: ev3brick.buttons + + +Light +----- + +.. autofunction:: ev3brick.light + + + +Sound +----- + +.. automethod:: ev3brick.sound.beep + + +.. automethod:: ev3brick.sound.beeps + + +.. automethod:: ev3brick.sound.file + + +Display +------- +:: + + x + --------------> + (0, 0) __________________ + | | + | | | + y | | Hello | + | | World | + v | | + |__________________| + (177, 127) + +.. automethod:: ev3brick.display.clear + +.. automethod:: ev3brick.display.text + +.. automethod:: ev3brick.display.image + +Battery +------- + +.. automethod:: ev3brick.battery.voltage + +.. automethod:: ev3brick.battery.current diff --git a/doc/ev3dev/ev3devices.rst b/doc/ev3dev/ev3devices.rst new file mode 100644 index 0000000..8a7679c --- /dev/null +++ b/doc/ev3dev/ev3devices.rst @@ -0,0 +1,70 @@ +:mod:`ev3devices` -- EV3 Motors and Sensors +=========================================== + +.. automodule:: ev3devices + :no-members: + +Motors +------ + +.. autoclass:: ev3devices.Motor + :no-members: + + .. rubric:: Methods for motors without rotation sensors + + .. automethod:: ev3devices.Motor.dc + + .. rubric:: Methods for motors with rotation sensors + + .. automethod:: ev3devices.Motor.angle + + .. automethod:: ev3devices.Motor.reset_angle + + .. automethod:: ev3devices.Motor.speed + + .. automethod:: ev3devices.Motor.stop + + .. automethod:: ev3devices.Motor.run + + .. automethod:: ev3devices.Motor.run_time + + .. automethod:: ev3devices.Motor.run_angle + + .. automethod:: ev3devices.Motor.run_target + + .. rubric:: Advanced methods for motors with rotation sensors + + .. automethod:: ev3devices.Motor.track_target + + .. automethod:: ev3devices.Motor.stalled + + .. automethod:: ev3devices.Motor.run_until_stalled + + .. automethod:: ev3devices.Motor.set_dc_settings + + .. automethod:: ev3devices.Motor.set_run_settings + + .. automethod:: ev3devices.Motor.set_pid_settings + +Sensors +------- + +Touch Sensor +^^^^^^^^^^^^ +.. autoclass:: ev3devices.TouchSensor + +Color Sensor +^^^^^^^^^^^^ +.. autoclass:: ev3devices.ColorSensor + +Infrared Sensor and Beacon +^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. autoclass:: ev3devices.InfraredSensor + +Ultrasonic Sensor +^^^^^^^^^^^^^^^^^ +.. autoclass:: ev3devices.UltrasonicSensor + +Gyroscopic Sensor +^^^^^^^^^^^^^^^^^ +.. autoclass:: ev3devices.GyroSensor diff --git a/doc/ev3dev/examples/color_sorter.rst b/doc/ev3dev/examples/color_sorter.rst new file mode 100644 index 0000000..3d359eb --- /dev/null +++ b/doc/ev3dev/examples/color_sorter.rst @@ -0,0 +1,19 @@ +Color Sorter +===================== + +This example program for the color sorter (:numref:`fig_color_sorter`) lets you scan colored Technic beams using the Color Sensor. + +Scan the colored beams one by one and add them to the tray. A beep confirms that it has registered the color. When the tray is full or when you press the center button, the robot will start distributing the Technic bricks by color. + +You can find building instructions for the color sorter on the `LEGO Education website `_. + +.. _fig_color_sorter: + +.. figure:: ../images/color_sorter.jpg + :width: 90 % + :alt: color_sorter + :align: center + + Color Sorter + +.. literalinclude:: ../../../examples/ev3/color_sorter/main.py diff --git a/doc/ev3dev/examples/robot_arm_h25.rst b/doc/ev3dev/examples/robot_arm_h25.rst new file mode 100644 index 0000000..ddf72eb --- /dev/null +++ b/doc/ev3dev/examples/robot_arm_h25.rst @@ -0,0 +1,19 @@ +Robot Arm H25 +===================== + +This example program makes the robot (:numref:`fig_robot_arm`) move the black wheel hub stacks around forever. The robot arm will first initialize and then start moving the hubs around. + +You can find building instructions for the robot on the `LEGO Education website `_. + +Tip: When building the robot, reverse the orientation of the EV3 Brick such that the microSD card is easily accessible. + +.. _fig_robot_arm: + +.. figure:: ../images/robot_arm.jpg + :width: 90 % + :alt: robot_arm + :align: center + + Robot Arm H25 + +.. literalinclude:: ../../../examples/ev3/robot_arm_h25/main.py diff --git a/doc/ev3dev/examples/robot_educator.rst b/doc/ev3dev/examples/robot_educator.rst new file mode 100644 index 0000000..dc9a973 --- /dev/null +++ b/doc/ev3dev/examples/robot_educator.rst @@ -0,0 +1,17 @@ +Robot Educator +===================== + +This example makes the Robot Educator (:numref:`fig_robot_educator`) drive until it sees an obstacle. It then backs up, turns around, and starts driving again. + +You can find building instructions for the Robot Educator on the `LEGO Education website `_. + +.. _fig_robot_educator: + +.. figure:: ../images/ultrasonic_sensor_driving_base.jpg + :width: 50 % + :alt: robot_educator + :align: center + + Robot Educator with the Ultrasonic Sensor + +.. literalinclude:: ../../../examples/ev3/robot_educator/main.py diff --git a/doc/ev3dev/images/.gitignore b/doc/ev3dev/images/.gitignore new file mode 100644 index 0000000..8ab8387 --- /dev/null +++ b/doc/ev3dev/images/.gitignore @@ -0,0 +1,3 @@ +*.png +!pybricks-logo-large.png +!pybricks-logo-small.png diff --git a/doc/ev3dev/images/color_sorter.jpg b/doc/ev3dev/images/color_sorter.jpg new file mode 100644 index 0000000..276634a Binary files /dev/null and b/doc/ev3dev/images/color_sorter.jpg differ diff --git a/doc/ev3dev/images/robot_arm.jpg b/doc/ev3dev/images/robot_arm.jpg new file mode 100644 index 0000000..c2de053 Binary files /dev/null and b/doc/ev3dev/images/robot_arm.jpg differ diff --git a/doc/ev3dev/images/ultrasonic_sensor_driving_base.jpg b/doc/ev3dev/images/ultrasonic_sensor_driving_base.jpg new file mode 100644 index 0000000..1de8b79 Binary files /dev/null and b/doc/ev3dev/images/ultrasonic_sensor_driving_base.jpg differ diff --git a/doc/ev3dev/index.rst b/doc/ev3dev/index.rst new file mode 100644 index 0000000..4725806 --- /dev/null +++ b/doc/ev3dev/index.rst @@ -0,0 +1,59 @@ +Using MicroPython with LEGO\ :sup:`®` MINDSTORMS\ :sup:`®` EV3 +============================================================== + +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 Brick 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 from your computer or from the EV3 Brick. + +After you've run the first demo program, you'll be ready to try out the example +programs and start inventing your own programs. + + +.. toctree:: + :maxdepth: 1 + :caption: Table of Contents + :hidden: + +.. toctree:: + :maxdepth: 1 + :caption: Getting Started + :hidden: + + startinstall + startrun + +.. toctree:: + :maxdepth: 1 + :caption: Pybricks Modules + :hidden: + + ev3brick + ev3devices + parameters + tools + robotics + +.. toctree:: + :maxdepth: 1 + :caption: Engineering Essentials + :hidden: + + signaltypes + +.. motorcontrol + +.. toctree:: + :maxdepth: 1 + :caption: Demo Programs + :hidden: + + examples/robot_educator + examples/color_sorter + examples/robot_arm_h25 diff --git a/doc/ev3dev/parameters.rst b/doc/ev3dev/parameters.rst new file mode 100644 index 0000000..d4db9fe --- /dev/null +++ b/doc/ev3dev/parameters.rst @@ -0,0 +1,29 @@ +:mod:`parameters` -- Parameters and Constants +============================================= + +.. automodule:: parameters + :no-members: + +.. autoclass:: parameters.Port + :no-members: + +.. autoclass:: parameters.Direction + :no-members: + +.. autoclass:: parameters.Stop + :no-members: + +.. autoclass:: parameters.Color + :no-members: + +.. autoclass:: parameters.Button + :no-members: + +.. autoclass:: parameters.Align + :no-members: + +.. autoclass:: parameters.ImageFile + :no-members: + +.. autoclass:: parameters.SoundFile + :no-members: diff --git a/doc/ev3dev/robotics.rst b/doc/ev3dev/robotics.rst new file mode 100644 index 0000000..b484435 --- /dev/null +++ b/doc/ev3dev/robotics.rst @@ -0,0 +1 @@ +.. include:: ../common/robotics.rst diff --git a/doc/ev3dev/signaltypes.rst b/doc/ev3dev/signaltypes.rst new file mode 100644 index 0000000..5ba65b5 --- /dev/null +++ b/doc/ev3dev/signaltypes.rst @@ -0,0 +1 @@ +.. include:: ../common/signaltypes.rst diff --git a/doc/ev3dev/startinstall.rst b/doc/ev3dev/startinstall.rst new file mode 100644 index 0000000..43ff42a --- /dev/null +++ b/doc/ev3dev/startinstall.rst @@ -0,0 +1,151 @@ +Installation +=================== + +This page guides you through the steps to collect and install everything you need to start programming. + +What do you need? +----------------------------------------------------------- + +To get started, you'll need: + +- A Windows 10 or Mac OS computer +- Internet access and administrator access + + This is required during the installation only. You will not need special access to write and run programs later on. + +- A microSD card + + You'll need a card with a minimum capacity of 4GB and a maximum capacity of 32GB. This type of microSD cards is also known as microSDHC. We recommend cards with Application Performance Class A1. + +- A microSD card slot or card reader in your computer + + If your computer does not have a (micro)SD card slot, you can use an external USB (micro)SD card reader. + +- A mini-USB cable, like the one included with your EV3 set + +The typical configuration of this equipment is summarized in :numref:`fig_overview`. + +.. _fig_overview: + +.. figure:: images/overview.png + :width: 90 % + :alt: overview + :align: center + + Setup overview + +Preparing your computer +----------------------------------------------------------- + +You'll write your MicroPython programs using Visual Studio Code. Follow the steps below to download, install, and configure this application: + +1. Download `Visual Studio Code `_. +2. Follow the on-screen instructions to install the application. +3. Launch Visual Studio Code. +4. Open the extensions tab. +5. Install the extension as shown in :numref:`fig_store`. + +.. _fig_store: + +.. figure:: images/store.png + :alt: store + :align: center + + Installing the extension from the Visual Studio Code marketplace + +.. _prepsdcard: + +Preparing the microSD card +----------------------------------------------------------- + +To make it possible to run MicroPython programs on your EV3 Brick, you'll now learn how to install the required tools on your microSD card. + +If the microSD card contains files you want to keep, make sure to create a backup of its contents first. See :ref:`managing files on the EV3 ` to learn how to backup your previous MicroPython programs if necessary. + +*This process erases everything on your microSD card, including any previous MicroPython programs on it.* + + +To install the MicroPython tools on your microSD card: + + +1. Download the `EV3 MicroPython microSD card image <.>`_ and save it in a convenient location. This file is approximately 360 MB. Do **not** open or unzip the file. +2. Download and install a microSD card flashing tool such as `Etcher `_. +3. Insert the microSD card into your computer or card reader. +4. Launch the flashing tool and follow the steps on your screen to install the file you have just downloaded. If you use Etcher, you can follow the instructions below, as shown in :numref:`fig_etcher`. + + a. Select the EV3 MicroPython microSD card image file you have just downloaded. + b. Select your microSD card. Make sure that the device and size correspond to your microSD card. + c. Start the flashing process. This may take several minutes. Do not remove the card until the flashing process is complete. + +.. _fig_etcher: + +.. figure:: images/etcher.png + :width: 85 % + :alt: etcher + :align: center + + Using Etcher to flash the EV3 MicroPython microSD card image + +Updating the microSD card +----------------------------------------------------------- + +To update the microSD card, download a new image file using the link above and flash it to the microSD card as described above. Be sure to :ref:`back up any MicroPython programs you want to save `. + +You do not need to erase the contents of the microSD card first. This is done automatically when you flash the new image file. + +Using the EV3 Brick +----------------------------------------------------------- + +Make sure the EV3 Brick is turned off. Insert the microSD card you prepared into the microSD card slot on the EV3 Brick, as shown in :numref:`fig_sd`. + +.. _fig_sd: + +.. figure:: images/sd.png + :width: 75 % + :alt: sd + :align: center + + Inserting the flashed microSD card into the EV3 Brick + + +Turning the EV3 Brick on and off +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Turn on the EV3 Brick by pressing the dark gray center button. + +The boot process may take several minutes. While booting, the EV3 Brick status light turns orange and blinks intermittently, and you'll see a lot of text on the EV3 screen. The EV3 Brick is ready for use when the status light turns green. + +To turn the EV3 Brick off, open the shutdown menu with the back button, and then select *Power Off* using the center button, as shown in :numref:`fig_onoff`. + +.. _fig_onoff: + +.. figure:: images/onoff.png + :width: 65 % + :alt: devicebrowser + :align: center + + Turning the EV3 Brick off + +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 in :numref:`fig_devicebrowser`. + +.. _fig_devicebrowser: + +.. figure:: images/devicebrowser.png + :width: 100 % + :alt: devicebrowser + :align: center + + Viewing motor and sensor values + +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 Brick off as shown above. +2. Wait for the screen and brick status light to turn off. +3. Remove the microSD card. +4. Turn the EV3 on. diff --git a/doc/ev3dev/startrun.rst b/doc/ev3dev/startrun.rst new file mode 100644 index 0000000..7d96089 --- /dev/null +++ b/doc/ev3dev/startrun.rst @@ -0,0 +1,151 @@ +Creating and running programs +============================= + +Now that you've set up your computer and EV3 Brick, you're ready to start writing programs. + +To make it easier to create and manage your programs, let's first have a quick look at how MicroPython projects and programs for your EV3 robots are organized. + +Programs are organized into *project folders*, as shown in :numref:`fig_projectstructure`. A project folder is a directory on your computer that contains the main program (**main.py**) and other optional scripts or files. This project folder and all of its contents will be copied to the EV3 Brick, where the main program will be run. + +This page shows you how to create such a project and how to transfer it to the EV3 Brick. + + +.. _fig_projectstructure: + +.. figure:: images/projectstructure.png + :width: 100 % + :alt: projectstructure + :align: center + + A project contains a program called **main.py** and optional resources like sounds or MicroPython modules. + + +Creating a new project +----------------------------------------------------------- + +To create a new project, open the Pybricks tab and click *create a new project*, as shown in :numref:`fig_newproject`. Enter a project name in the text field that appears and press *Enter*. When prompted, choose a location for this program and confirm by clicking *choose folder*. + +.. _fig_newproject: + +.. figure:: images/newproject.png + :width: 100 % + :alt: newproject + :align: center + + Creating a new project. This example is called *getting_started*, but you can choose any name. + +When you create a new project, it already includes a file called *main.py*. To see its contents and to modify it, open it from the file browser as shown in :numref:`fig_projectoverview`. This is where you'll write your programs. + +If you are new to MicroPython programming, we recommend that you keep the existing code in place and add your code to it. + +.. _fig_projectoverview: + +.. figure:: images/projectoverview.png + :width: 100 % + :alt: projectoverview + :align: center + + Opening the default *main.py* program. + +Opening an existing project +----------------------------------------------------------- + +To open a project you created previously, click *File* and click *Open Folder*, as shown in :numref:`fig_existingproject`. Next, navigate to your previously created project folder and click *OK*. You can also open your recently used projects using the *Open Recent* menu option. + +.. _fig_existingproject: + +.. figure:: images/existingproject.png + :width: 75 % + :alt: existingproject + :align: center + + Opening a previously created project. + +Connecting to the EV3 Brick with Visual Studio Code +----------------------------------------------------------- + +To be able to transfer your code to the EV3 Brick, you'll first need to connect the EV3 Brick to your computer with the mini-USB cable and configure the connection with Visual Studio Code. To do so: + +- Turn the EV3 Brick on +- Connect the EV3 Brick to your computer with the mini-USB cable +- Configure the USB connection as shown in :numref:`fig_connecting`. + +.. _fig_connecting: + +.. figure:: images/connecting.png + :width: 100 % + :alt: connecting + :align: center + + Configuring the USB connection between the computer and the EV3 Brick + +Downloading and running a program +----------------------------------------------------------- + +You can press the F5 key to run the program. Alternatively, you can start it manually by going to the *debug* tab and clicking the green start arrow, as shown in :numref:`fig_running`. + +When the program starts, a pop-up toolbar allows you to stop the program if necessary. You can also stop the program at any time using the back button on the EV3 Brick. + +If your program produces any output with the :mod:`print <.tools>` command, this is shown in the output window. + +.. _fig_running: + +.. figure:: images/running.png + :width: 100 % + :alt: running + :align: center + + Running a program + +Expanding the example program +----------------------------------------------------------- + +Now that you've run the basic code template, you can expand the program to make a motor move. First, attach a Large Motor to Port B on the EV3 Brick, as shown in :numref:`fig_firstprogram`. + +.. _fig_firstprogram: + +.. figure:: images/firstprogram.png + :width: 100 % + :alt: firstprogram + :align: center + + The EV3 Brick with a Large Motor attached to port B. + +Next, edit *main.py* to make it look like this: + +.. literalinclude:: ../../examples/ev3/getting_started/main.py + +This program makes your robot beep, rotate the motor, and beep again with a higher pitched tone. Run the program to make sure that it works as expected. + +.. _managefiles: + +Managing files on the EV3 Brick +----------------------------------------------------------- + +After you've downloaded a project to the EV3 Brick, you can run, delete, or back up programs stored on it using the device browser as shown in in :numref:`fig_files`. + +.. _fig_files: + +.. figure:: images/files.png + :width: 100 % + :alt: files + :align: center + + Using the device browser to manage files on your EV3 Brick + + +Running a program without a computer +----------------------------------------------------------- + +You can run previously downloaded programs directly from the EV3 Brick. + +To do so, find the program using the *file browser* on the EV3 screen and press the center button key to start the program as shown in in :numref:`fig_manualrun`. + +.. _fig_manualrun: + +.. figure:: images/manualrun.png + :width: 100 % + :alt: manualrun + :align: center + + Starting a program using the buttons on the EV3 Brick diff --git a/doc/ev3dev/tools.rst b/doc/ev3dev/tools.rst new file mode 100644 index 0000000..5eeb890 --- /dev/null +++ b/doc/ev3dev/tools.rst @@ -0,0 +1 @@ +.. include:: ../common/tools.rst diff --git a/doc/lpf2/_images/Makefile b/doc/lpf2/_images/Makefile new file mode 100755 index 0000000..cf15c72 --- /dev/null +++ b/doc/lpf2/_images/Makefile @@ -0,0 +1,15 @@ + +SRC_DIR = . +OUT_DIR = ../images + +SVG := $(wildcard $(SRC_DIR)/*.svg) +PNG := $(patsubst $(SRC_DIR)/%.svg,$(OUT_DIR)/%.png,$(SVG)) +DIR := ${CURDIR} + +all: $(PNG) + +clean: + rm -f $(PNG) + +$(OUT_DIR)/%.png: $(SRC_DIR)/%.svg + inkscape --file=$(DIR)/$< --export-area-drawing --export-png=$(DIR)/$@ diff --git a/doc/lpf2/_images/overview.jpg b/doc/lpf2/_images/overview.jpg new file mode 100644 index 0000000..07be516 Binary files /dev/null and b/doc/lpf2/_images/overview.jpg differ diff --git a/doc/lpf2/_images/overview.svg b/doc/lpf2/_images/overview.svg new file mode 100644 index 0000000..0059c3d --- /dev/null +++ b/doc/lpf2/_images/overview.svg @@ -0,0 +1,251 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + Computer with Visual Studio Code + + + + + Download and run + + + MicroSD card withEV3 MicroPython image + + + + + Mini-USB cable + + + + + + + EV3 Brick + diff --git a/doc/lpf2/conf.py b/doc/lpf2/conf.py new file mode 100644 index 0000000..a426e43 --- /dev/null +++ b/doc/lpf2/conf.py @@ -0,0 +1,8 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Pybricks documentation build configuration file +# +import os +import sys +exec(open(os.path.abspath("../common/conf.py")).read()) diff --git a/doc/lpf2/examples/line_follower.rst b/doc/lpf2/examples/line_follower.rst new file mode 100644 index 0000000..ec36796 --- /dev/null +++ b/doc/lpf2/examples/line_follower.rst @@ -0,0 +1,6 @@ +Line follower +===================== + +This is a nonexisting example: + +.. literalinclude:: ../../../examples/ev3/robot_educator/main.py diff --git a/doc/lpf2/hub4.rst b/doc/lpf2/hub4.rst new file mode 100644 index 0000000..91487ed --- /dev/null +++ b/doc/lpf2/hub4.rst @@ -0,0 +1,12 @@ +:mod:`hub4` -- LEGO® Power Functions 2.0 Hub 4 +===================================================== + +.. automodule:: hub4 + :no-members: + +Battery +------- + +.. automethod:: hub4.battery.voltage + +.. automethod:: hub4.battery.current diff --git a/doc/lpf2/images/.gitignore b/doc/lpf2/images/.gitignore new file mode 100644 index 0000000..8ab8387 --- /dev/null +++ b/doc/lpf2/images/.gitignore @@ -0,0 +1,3 @@ +*.png +!pybricks-logo-large.png +!pybricks-logo-small.png diff --git a/doc/lpf2/index.rst b/doc/lpf2/index.rst new file mode 100644 index 0000000..e433f7e --- /dev/null +++ b/doc/lpf2/index.rst @@ -0,0 +1,44 @@ +Pybricks for Power Functions 2.0 +============================================================== + +Intro + +.. toctree:: + :maxdepth: 1 + :caption: Table of Contents + :hidden: + +.. toctree:: + :maxdepth: 1 + :caption: Getting Started + :hidden: + + startinstall + startrun + +.. toctree:: + :maxdepth: 1 + :caption: Pybricks Modules + :hidden: + + movehub + hub4 + lpf2devices + parameters + tools + robotics + +.. toctree:: + :maxdepth: 1 + :caption: Engineering Essentials + :hidden: + + signaltypes + +.. toctree:: + :maxdepth: 1 + :caption: Demo Programs + :hidden: + + examples/line_follower + diff --git a/doc/lpf2/lpf2devices.rst b/doc/lpf2/lpf2devices.rst new file mode 100644 index 0000000..3ef43a3 --- /dev/null +++ b/doc/lpf2/lpf2devices.rst @@ -0,0 +1,54 @@ +:mod:`lpf2devices` -- Power Function 2.0 Motors and Sensors +=========================================================== + +.. automodule:: lpf2devices + :no-members: + +Motors +------ + +.. autoclass:: lpf2devices.Motor + :no-members: + + .. rubric:: Methods for motors without rotation sensors + + .. automethod:: lpf2devices.Motor.dc + + .. rubric:: Methods for motors with rotation sensors + + .. automethod:: lpf2devices.Motor.angle + + .. automethod:: lpf2devices.Motor.reset_angle + + .. automethod:: lpf2devices.Motor.speed + + .. automethod:: lpf2devices.Motor.stop + + .. automethod:: lpf2devices.Motor.run + + .. automethod:: lpf2devices.Motor.run_time + + .. automethod:: lpf2devices.Motor.run_angle + + .. automethod:: lpf2devices.Motor.run_target + + .. rubric:: Advanced methods for motors with rotation sensors + + .. automethod:: lpf2devices.Motor.track_target + + .. automethod:: lpf2devices.Motor.stalled + + .. automethod:: lpf2devices.Motor.run_until_stalled + + .. automethod:: lpf2devices.Motor.set_dc_settings + + .. automethod:: lpf2devices.Motor.set_run_settings + + .. automethod:: lpf2devices.Motor.set_pid_settings + +Sensors +------- + +Color and Distance Sensor +^^^^^^^^^^^^^^^^^^^^^^^^^ +.. autoclass:: lpf2devices.ColorDistanceSensor diff --git a/doc/lpf2/movehub.rst b/doc/lpf2/movehub.rst new file mode 100644 index 0000000..db6eaf6 --- /dev/null +++ b/doc/lpf2/movehub.rst @@ -0,0 +1,12 @@ +:mod:`movehub` -- LEGO® Power Functions 2.0 Move Hub +==================================================== + +.. automodule:: movehub + :no-members: + +Battery +------- + +.. automethod:: movehub.battery.voltage + +.. automethod:: movehub.battery.current diff --git a/doc/lpf2/parameters.rst b/doc/lpf2/parameters.rst new file mode 100644 index 0000000..8cac994 --- /dev/null +++ b/doc/lpf2/parameters.rst @@ -0,0 +1,20 @@ +:mod:`parameters` -- Parameters and Constants +============================================= + +.. automodule:: parameters + :no-members: + +.. autoclass:: parameters.Port + :no-members: + +.. autoclass:: parameters.Direction + :no-members: + +.. autoclass:: parameters.Stop + :no-members: + +.. autoclass:: parameters.Color + :no-members: + +.. autoclass:: parameters.Button + :no-members: diff --git a/doc/lpf2/robotics.rst b/doc/lpf2/robotics.rst new file mode 100644 index 0000000..b484435 --- /dev/null +++ b/doc/lpf2/robotics.rst @@ -0,0 +1 @@ +.. include:: ../common/robotics.rst diff --git a/doc/lpf2/signaltypes.rst b/doc/lpf2/signaltypes.rst new file mode 100644 index 0000000..5ba65b5 --- /dev/null +++ b/doc/lpf2/signaltypes.rst @@ -0,0 +1 @@ +.. include:: ../common/signaltypes.rst diff --git a/doc/lpf2/startinstall.rst b/doc/lpf2/startinstall.rst new file mode 100644 index 0000000..8ba1c8f --- /dev/null +++ b/doc/lpf2/startinstall.rst @@ -0,0 +1,14 @@ +Installation +=================== + +Getting started. See :numref:`fig_overview`. + +.. _fig_overview: + +.. figure:: images/overview.png + :width: 90 % + :alt: overview + :align: center + + Setup overview + diff --git a/doc/lpf2/startrun.rst b/doc/lpf2/startrun.rst new file mode 100644 index 0000000..fe5b299 --- /dev/null +++ b/doc/lpf2/startrun.rst @@ -0,0 +1,4 @@ +Creating and running programs +============================= + +Running programs. diff --git a/doc/lpf2/tools.rst b/doc/lpf2/tools.rst new file mode 100644 index 0000000..5eeb890 --- /dev/null +++ b/doc/lpf2/tools.rst @@ -0,0 +1 @@ +.. include:: ../common/tools.rst diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..12b8a86 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=%SOURCEDIR%/build +set SPHINXPROJ=Pybricks + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd