mirrors/micropython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/wipy: Add more tutorials and examples.

Browse Source
This commit is contained in:
danicampora 2015-10-21 14:58:04 +02:00
parent 075ca64521
commit 109b363ddc
7 changed files with 370 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/wipy/general.rst
View File

@ -8,8 +8,8 @@ Due to space reasons, there's no floating point support, and no math module. Thi
means that floating point numbers cannot be used anywhere in the code, and that
all divisions must be performed using '//' instead of '/'. Example::
r = 4 // 2 # this will work
r = 4 / 2 # this WON'T
>>> r = 4 // 2 # this will work
>>> r = 4 / 2 # this WON'T
Before applying power
---------------------
@ -31,6 +31,8 @@ to gain access to the interactive prompt, open a telnet session to that IP addre
the default port (23). You will be asked for credentials:
``login: micro`` and ``password: python``
.. _wipy_telnet:
Telnet REPL
-----------
@ -51,7 +53,7 @@ is hooked-up and mounted, it will be available as well.
When the WiPy starts up, it always boots from the ``boot.py`` located in the
``/flash`` file system.
The file system is accessible via the native FTP server running in the WiPy.
The file system is accessible via the native FTP server running in the WiPy.
Open your FTP client of choice and connect to:
**url:** ``ftp://192.168.1.1``, **user:** ``micro``, **password:** ``python``
@ -91,15 +93,25 @@ ends up inside the internal **hidden** file system, but rest assured that it was
transferred, and it has been signed with a MD5 checksum to verify its integrity. Now, reset
the WiPy by pressing the switch on the board, or by typing::
import machine
machine.reset()
>>> import machine
>>> machine.reset()
Software updates can be found in: https://github.com/wipy/wipy/releases
It's always recommended to update to the latest software, but make sure to
read the **release notes** before.
Boot modes
----------
In order to check your software version, do::
>>> import os
>>> os.uname().release
If the version number is lower than the latest release found in
`the releases <https://github.com/wipy/wipy/releases>`_, go ahead and update your WiPy!
.. _wipy_boot_modes:
Boot modes and safe boot
------------------------
If you power up normally, or press the reset button, the WiPy will boot
into standard mode; the ``boot.py`` file will be executed first, then
@ -110,7 +122,7 @@ it to the 3v3 output pin) during reset. This procedure also allows going
back in time to old firmware versions. The WiPy can hold up to 3 different
firmware versions, which are: the factory firmware plus 2 user updates.
After reset, if ``GP28`` is held high, the heart beat LED will start flashing
After reset, if ``GP28`` is held high, the heartbeat LED will start flashing
slowly, if after 3 seconds the pin is still being held high, the LED will start
blinking a bit faster and the WiPy will select the previous user update to boot.
If the previous user update is the desired firmware image, ``GP28`` must be
@ -134,19 +146,19 @@ useful to recover from crash situations caused by the user scripts. The selectio
made during safe boot is not persistent, meaning that after the next normal reset,
the latest firmware will run again.
The heart beat LED
The heartbeat LED
------------------
By default the heart beat LED flashes once every 4s to signal that the system is
By default the heartbeat LED flashes once every 4s to signal that the system is
alive. This can be overridden through the :mod:`wipy` module::
import wipy
wipy.heartbeat(False)
>>> import wipy
>>> wipy.heartbeat(False)
There are currently 2 kinds of errors that you might see:
1. If the heart beat LED flashes quickly, then a Python script(eg ``main.py``)
1. If the heartbeat LED flashes quickly, then a Python script(eg ``main.py``)
has an error. Use the REPL to debug it.
2. If the heart beat LED stays on, then there was a hard fault, you cannot
2. If the heartbeat LED stays on, then there was a hard fault, you cannot
recover from this, the only way out is to press the reset switch.

19
docs/wipy/tutorial/blynk.rst Normal file
View File

@ -0,0 +1,19 @@
Getting started with Blynk and the WiPy
---------------------------------------
Blynk is a platform with iOS and Android apps to control
Arduino, Raspberry Pi and the likes over the Internet.
You can easily build graphic interfaces for all your
projects by simply dragging and dropping widgets.
There are several examples available that work out-of-the-box with
the WiPy. Before anything else, make sure that your WiPy is running
the latest software, check :ref:`OTA How-To <wipy_firmware_upgrade>` for instructions.
1. Get the `Blynk library <https://github.com/wipy/wipy/blob/master/lib/blynk/BlynkLib.py>`_ and put it in ``/flash/lib/`` via FTP.
2. Get the `Blynk examples <https://github.com/wipy/wipy/tree/master/examples/blynk>`_ edit the network settings, and afterwards
upload them to ``/flash/lib/`` via FTP as well.
3. Follow the instructions on each example to setup the Blynk dashboard on your smartphone or tablet.
4. Give it a try, for instance::
>>> execfile('01_simple.py')

33
docs/wipy/tutorial/index.rst
View File

@ -3,28 +3,15 @@
WiPy tutorials and examples
===========================
Performing firmware upgrades
----------------------------
Before starting, make sure that you are running the latest firmware,
for instrucctions see :ref:`OTA How-To <wipy_firmware_upgrade>`.
For detalied instructions see :ref:`OTA How-To <wipy_firmware_upgrade>`.
Getting started with Blynk and the WiPy
---------------------------------------
Blynk is a platform with iOS and Android apps to control
Arduino, Raspberry Pi and the likes over the Internet.
You can easily build graphic interfaces for all your
projects by simply dragging and dropping widgets.
There are several examples available that work out-of-the-box with
the WiPy. Before anything else, make sure that your WiPy is running
the latest software, check :ref:`OTA How-To <wipy_firmware_upgrade>`.
1. Get the `Blynk library <https://github.com/wipy/wipy/blob/master/lib/blynk/BlynkLib.py>`_ and put it in ``/flash/lib/`` via FTP.
2. Get the `Blynk examples <https://github.com/wipy/wipy/tree/master/examples/blynk>`_ edit the network settings, and afterwards
upload them to ``/flash/lib/`` via FTP as well.
3. Follow the instructions on each example to setup the Blynk dashboard on your smartphone.
4. Give it a try, for instance::
>>> execfile('01_simple.py')
.. toctree::
:maxdepth: 1
:numbered:
intro.rst
repl.rst
blynk.rst
wlan.rst
reset.rst

64
docs/wipy/tutorial/intro.rst Normal file
View File

@ -0,0 +1,64 @@
Introduction to the WiPy
========================
To get the most out of your WiPy, there are a few basic things to
understand about how it works.
Caring for your WiPy and expansion board
----------------------------------------
Because the WiPy/expansion board does not have a housing it needs a bit of care:
- Be gentle when plugging/unplugging the USB cable. Whilst the USB connector
is well soldered and is relatively strong, if it breaks off it can be very
difficult to fix.
- Static electricity can shock the components on the WiPy and destroy them.
If you experience a lot of static electricity in your area (eg dry and cold
climates), take extra care not to shock the WiPy. If your WiPy came
in a ESD bag, then this bag is the best way to store and carry the
pyboard as it will protect it agains static discharges.
As long as you take care of the hardware, you should be okay. It's almost
impossible to break the software on the WiPy, so feel free to play around
with writing code as much as you like. If the filesystem gets corrupt, see
below on how to reset it. In the worst case you might need to do a safe boot,
which is explained in detail :ref:`here <wipy_boot_modes>`.
Plugging into the expansion board and powering on
-------------------------------------------------
The expansion board can power the WiPy via USB. The WiPy comes with a sticker
on top of the RF shield tha labels all pins, and this should match the label
numbers on the expansion board headers. When pluggin it in, the WiPy antenna
will end up on top of the SD card connector of the expansion board. A video
showing how to do this can be found `here <https://www.youtube.com/watch?v=47D9MZ9zFQw>`_.
Expansion board hardware guide
------------------------------
The document explaining the hardware details of the expansion board can be found
`here <https://github.com/wipy/wipy/blob/master/docs/User_manual_exp_board.pdf>`_.
Powering by an external power source
------------------------------------
The WiPy can be powered by a battery or other external power source.
**Be sure to connect the positive lead of the power supply to VIN, and
ground to GND. There is no polarity protection on the pyboard so you
must be careful when connecting anything to VIN.**
- When powering via ``VIN``:
**The input voltage must be between 3.6V and 5.5V.**
- When powering via ``3V3``:
**The input volatge must be exactly 3V3, ripple free and from a supply capable
of sourcing at least 300mA of current**
Performing firmware upgrades
----------------------------
For detalied instructions see :ref:`OTA How-To <wipy_firmware_upgrade>`.

137
docs/wipy/tutorial/repl.rst Normal file
View File

@ -0,0 +1,137 @@
Getting a MicroPython REPL prompt
=================================
REPL stands for Read Evaluate Print Loop, and is the name given to the
interactive MicroPython prompt that you can access on the WiPy. Using
the REPL is by far the easiest way to test out your code and run commands.
You can use the REPL in addition to writing scripts in ``main.py``.
To use the REPL, you must connect to the WiPy either via :ref:`telnet <wipy_telnet>`,
or with a USB to serial converter wired to the one the two UARTs on the
WiPy. To enable REPL duplication on UART0 (the one accesible via the expansion board)
do::
>>> from machine import UART
>>> import os
>>> uart = UART(0, 115200)
>>> o.dupterm(uart)
Place this piece of code inside your `boot.py` so that it's done automatically after
reset.
Windows
-------
You need to install the pyboard driver to use the serial USB device.
The driver is on the pyboard's USB flash drive, and is called ``pybcdc.inf``.
To install this driver you need to go to Device Manager
for your computer, find the pyboard in the list of devices (it should have
a warning sign next to it because it's not working yet), right click on
the pyboard device, select Properties, then Install Driver. You need to
then select the option to find the driver manually (don't use Windows auto update),
navigate to the pyboard's USB drive, and select that. It should then install.
After installing, go back to the Device Manager to find the installed pyboard,
and see which COM port it is (eg COM4).
More comprehensive instructions can be found in the
`Guide for pyboard on Windows (PDF) <http://micropython.org/resources/Micro-Python-Windows-setup.pdf>`_.
Please consult this guide if you are having problems installing the driver.
The best option is to download the free program PuTTY:
`putty.exe <http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html>`_.
**In order to get to the telnet REPL:**
Using putty, select ``Telnet`` as connection type, leave the default port (23)
and enter the IP address of your WiPy (192.168.1.1 when in ``WLAN.AP`` mode),
then click open.
**In order to get to the REPL UART:**
Using your serial program you must connect to the COM port that you found in the
previous step. With PuTTY, click on "Session" in the left-hand panel, then click
the "Serial" radio button on the right, then enter you COM port (eg COM4) in the
"Serial Line" box. Finally, click the "Open" button.
Mac OS X
--------
Open a terminal and run::
$ telnet 192.168.1.1
or::
$ screen /dev/tty.usbmodem* 115200
When you are finished and want to exit screen, type CTRL-A CTRL-\\.
Linux
-----
Open a terminal and run::
$ telnet 192.168.1.1
or::
$ screen /dev/ttyUSB0 115200
You can also try ``picocom`` or ``minicom`` instead of screen. You may have to
use ``/dev/ttyUSB01`` or a higher number for ``ttyUSB``. And, you may need to give
yourself the correct permissions to access this devices (eg group ``uucp`` or ``dialout``,
or use sudo).
Using the REPL prompt
---------------------
Now let's try running some MicroPython code directly on the WiPy.
With your serial program open (PuTTY, screen, picocom, etc) you may see a blank
screen with a flashing cursor. Press Enter and you should be presented with a
MicroPython prompt, i.e. ``>>>``. Let's make sure it is working with the obligatory test::
>>> print("hello WiPy!")
hello WiPy!
In the above, you should not type in the ``>>>`` characters. They are there to
indicate that you should type the text after it at the prompt. In the end, once
you have entered the text ``print("hello pyboard!")`` and pressed Enter, the output
on your screen should look like it does above.
If you already know some python you can now try some basic commands here.
If any of this is not working you can try either a hard reset or a soft reset;
see below.
Go ahead and try typing in some other commands. For example::
>>> from machine import Pin
>>> import wipy
>>> wipy.heartbeat(False) # disable the heartbeat
>>> led = Pin('GP25', mode=Pin.OUT)
>>> led(1)
>>> led(0)
>>> led.toggle()
>>> 1 + 2
3
>>> 4 // 2
2
>>> 20 * 'py'
'pypypypypypypypypypypypypypypypypypypypy'
Resetting the board
-------------------
If something goes wrong, you can reset the board in two ways. The first is to press CTRL-D
at the MicroPython prompt, which performs a soft reset. You will see a message something like::
>>>
PYB: soft reboot
MicroPython v1.4.6-146-g1d8b5e5 on 2015-10-21; WiPy with CC3200
Type "help()" for more information.
>>>
If that isn't working you can perform a hard reset (turn-it-off-and-on-again) by pressing the
RST switch (the small black button next to the heartbeat LED). During telnet, this will end
your session, disconnecting whatever program that you used to connect to the WiPy.

53
docs/wipy/tutorial/reset.rst Normal file
View File

@ -0,0 +1,53 @@
Reset and boot modes
====================
There are soft resets and hard resets.
- A soft reset simply clears the state of the MicroPython virtual machine,
but leaves hardware peripherals unaffected. To do a soft reset, simply press
**Ctrl+D** on the REPL, or within a script do::
import sys
sys.exit()
- A hard reset is the same as performing a power cycle to the board. In order to
hard reset the WiPy, press the switch on the board or::
import machine
machine.reset()
Safe boot
---------
If something goes wrong with your WiPy, don't panic! It is almost
impossible for you to break the WiPy by programming the wrong thing.
The first thing to try is to boot in safe mode: this temporarily skips
execution of ``boot.py`` and ``main.py`` and gives default WLAN settings.
If you have problems with the filesystem you can :ref:`format the internal flash
drive <wipy_factory_reset>`.
To boot in safe mode, follow the detailed instructions described :ref:`here <wipy_boot_modes>`.
In safe mode, the ``boot.py`` and ``main.py`` files are not executed, and so
the WiPy boots up with default settings. This means you now have access
to the filesystem, and you can edit ``boot.py`` and ``main.py`` to fix any problems.
Entering safe mode is temporary, and does not make any changes to the
files on the WiPy.
.. _wipy_factory_reset:
Factory reset the filesystem
----------------------------
If you WiPy's filesystem gets corrupted (very unlikely, but possible), you
can format it very easily byt doing::
>>> import os
>>> os.mkfs('/flash')
Resetting the filesystem deletes all files on the internal WiPy storage
(not the SD card), and restores the files ``boot.py``, ``main.py``, ``README.txt``
and ``pybcdc.inf`` back to their original state after the next reset.

61
docs/wipy/tutorial/wlan.rst Normal file
View File

@ -0,0 +1,61 @@
WLAN step by step
=================
The WLAN is a system feature of the WiPy, therefore it is always enabled
(even while in ``machine.SLEEP``), except when deepsleep mode is entered.
In order to retrieve the current WLAN instance, do::
>>> from network import WLAN
>>> wlan = WLAN() # we call the constructor without params
You can check the current mode (which is always ``WLAN.AP`` after power up)::
>>> wlan.mode()
Connecting to your home router
------------------------------
The WLAN network card always boots in ``WLAN.AP`` mode, so we must first configure
it as a station::
from network import WLAN
wlan = WLAN(mode=WLAN.STA)
Now you can proceed to scan for networks::
nets = wlan.scan()
for net in nets:
if net.ssid == 'mywifi':
print('Network found!')
wlan.connect(net.ssid, auth=(net.sec, 'mywifikey'), timeout=5000)
while not wlan.isconnected():
machine.idle() # save power while waiting
print('WLAN connection succeeded!)
break
Assigning a static IP address when booting
------------------------------------------
If you want your WiPy to connect to your home router while after boot-up, and with a fixed
IP address so that you can access it via telnet or FTP, use the following script::
import machine
from network import WLAN
wlan = WLAN() # get current object, without changing the mode
if machine.reset_cause() != machine.SOFT_RESET:
wlan.init(WLAN.STA)
# configuration below MUST match your home router settings!!
wlan.ifconfig(config=('192.168.178.107', '255.255.255.0', '192.168.178.1', '8.8.8.8'))
if not wlan.isconnected():
wlan.connect(net.ssid, auth=(net.sec, 'mywifikey'), timeout=5000)
while not wlan.isconnected():
machine.idle() # save power while waiting
break
.. note::
Notice how we check for the reset cause and the connection status, this is crucial in order
to be able to soft reset the WiPy during a telnet session without breaking the connection.