Getting started
===============

First things first
__________________

* Download and install `PuTTY <https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html>`_
* Download and install `Notepad++ <https://notepad-plus-plus.org/downloads/>`_

Powering the board
__________________

| omega:ONE and omega:TWO can be powered directly through the USB-C connector.
| alpha:ONE needs to be supplied with 6-36 V. Alternatively, to power the board through the micro-USB connector set JP2.

Accessing MicroPython interactive prompt
________________________________________

| The MicroPython interactive prompt "REPL" (as in Read-Evaluate-Print-Loop) is the easiest way to test your code and run commands: the code you type in the terminal is evaluated when you hit enter, and the result is displayed right away.
| However, there is no persistance and everything you type is lost after a reset (soft reset or hard reset/power cycle).

| You can use the interactive prompt to quickly test some commands, debug code and see what kind of object a specific function or line of code returns.
| Remember to switch to paste mode using ``Ctrl+E`` before pasting multi-line sections of code into the REPL, otherwise the indentations will not be entered correctly, and the REPL will report an indentation error.
| After pasting the code, hit ``Ctrl+D`` to run the code and switch back to normal REPL mode.

| The interactive prompt REPL can be accessed with any terminal program, such as `PuTTY <https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html>`_, by opening the board's USB serial port, which is automatically created when the board is connected to a PC:
| On your computer open `Control Panel` > `Device Manager` and scroll down to `Ports (COM & LPT)`.
| With the Device Manager still open, connect the board to your computer with the USB cable and you'll see the new COM port appear - remember this COM port number.

.. figure:: /images/device_manager_com_port_01.png
    :align: center
    :width: 80%

| Open PuTTY, select `Serial`, insert the COM port corresponding to the board and then click the `Open` button.
| (`Speed` is not relevant in this context of a USB virtual COM port and can be left to any value).

.. figure:: /images/putty_select_serial_01.png
    :align: center
    :width: 80%

| In the terminal window you'll see printed the micropython version and compilation date first, followed by the board name and microcontroller type.
| The characters ``>>>`` are the REPL prompt: try inputting some code like ``1 + 1`` or ``print("Hello world!")`` and hit the `Enter` key!

.. figure:: /images/Putty_REPL.png
    :align: center
    :width: 80%

| Useful commands in REPL:

.. list-table::
         :widths: 5 20
         :align: center

         * - ``help()``
           - prints information about the board

         * - ``help(object)``
           - gives information on a specific Micropython ``object``

         * - ``Tab``
           - autocompletes commands as you type them

         * - ``Tab``
           - on an empty REPL prompt lists all the valid commands and objects currently in RAM

.. admonition:: official MycroPython documentation
   :class: note

   `Micropython REPL <https://docs.micropython.org/en/latest/reference/repl.html>`_

Automatically executing a script
________________________________

| MicroPython provides a way to save some code on the board and automatically execute it when powering up after a reset (either a power cycle or a soft/hard reset):
| If the files exist, Micropython will first run ``boot.py`` and then ``main.py``.

| ``boot.py`` is meant to contain code needed to setup the board and is usually kept fairly short.
| ``main.py`` is where you should put the actual code for your application.

.. admonition:: official MycroPython documentation
   :class: note

   `local filesystem and SD card <https://docs.micropython.org/en/latest/pyboard/general.html#local-filesystem-and-sd-card>`_

So let's try this out! Connect the board to your computer via the USB cable. The board's flash storage will show up as a normal USB drive named `PYBFLASH`.
(If `File Explorer` doesn't pop up automatically, open it manually and you'll see `PYBFLASH` under your computer's drives).

.. figure:: /images/file_explorer_01.png
    :align: center
    :width: 80%

| Open ``main.py`` with Notepad++ (right mouse click -> `Edit with Notepad++`).
| Copy paste the following code into Notepad++:

.. code-block:: python

    # main.py -- put your code here!
    import pyb

    # print a header line
    print('#### Test ####')

    # infinite loop
    while True:
        print('Hello world!')

        # wait for one second (1000 milliseconds)
        pyb.delay(1000)

| Save the file (click save button on Notepad++ or hit ``Ctrl + S``).
| An LED on the board will briefly light up while the data is being written to the flash.

.. figure:: /images/Notepadpp_Main.png
    :align: center
    :width: 80%

| Now your code is saved on the board and will be run automatically as soon as you reset the board.
| Go back to the interactive prompt REPL on Putty and perform a soft reset by hitting ``Ctrl + D``.

.. figure:: /images/Putty_Main.png
    :align: center
    :width: 80%

| As you see, the code you entered in ``main.py`` is executed automatically and the output is desplayed in the interactive prompt.
| You can interrupt the execution of the program and go back to the REPL prompt by hitting ``Ctrl + C`` in Putty.

REPL keyboard shortcuts summary:

.. list-table::
   :widths: 11 60
   :align: center

   * - ``Ctrl + C``
     - stop a running program, for instance the ``main.py`` script and go back to the REPL

   * - ``Ctrl + D``
     - force a soft reboot, for instance to run ``main.py`` after modifying it

   * - ``Ctrl + E``
     - switch to paste mode, to paste multiple lines of code without indentation errors

   * - ``Ctrl + D``
     - in paste mode, execute the code entered and go back to normal REPL mode