Skip to content

Commit 109b363

Browse files
author
danicampora
committed
docs/wipy: Add more tutorials and examples.
1 parent 075ca64 commit 109b363

File tree

7 files changed

+372
-39
lines changed

7 files changed

+372
-39
lines changed

‎docs/wipy/general.rst‎

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ Due to space reasons, there's no floating point support, and no math module. Thi
88
means that floating point numbers cannot be used anywhere in the code, and that
99
all divisions must be performed using '//' instead of '/'. Example::
1010

11-
r = 4 // 2 # this will work
12-
r = 4 / 2 # this WON'T
11+
>>> r = 4 // 2 # this will work
12+
>>> r = 4 / 2 # this WON'T
1313

1414
Before applying power
1515
---------------------
@@ -31,6 +31,8 @@ to gain access to the interactive prompt, open a telnet session to that IP addre
3131
the default port (23). You will be asked for credentials:
3232
``login: micro`` and ``password: python``
3333

34+
.. _wipy_telnet:
35+
3436
Telnet REPL
3537
-----------
3638

@@ -51,7 +53,7 @@ is hooked-up and mounted, it will be available as well.
5153
When the WiPy starts up, it always boots from the ``boot.py`` located in the
5254
``/flash`` file system.
5355

54-
The file system is accessible via the native FTP server running in the WiPy.
56+
The file system is accessible via the native FTP server running in the WiPy.
5557
Open your FTP client of choice and connect to:
5658

5759
**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
9193
transferred, and it has been signed with a MD5 checksum to verify its integrity. Now, reset
9294
the WiPy by pressing the switch on the board, or by typing::
9395

94-
import machine
95-
machine.reset()
96+
>>> import machine
97+
>>> machine.reset()
9698

9799
Software updates can be found in: https://github.com/wipy/wipy/releases
98100
It's always recommended to update to the latest software, but make sure to
99101
read the **release notes** before.
100102

101-
Boot modes
102-
----------
103+
In order to check your software version, do::
104+
105+
>>> import os
106+
>>> os.uname().release
107+
108+
If the version number is lower than the latest release found in
109+
`the releases <https://github.com/wipy/wipy/releases>`_, go ahead and update your WiPy!
110+
111+
.. _wipy_boot_modes:
112+
113+
Boot modes and safe boot
114+
------------------------
103115

104116
If you power up normally, or press the reset button, the WiPy will boot
105117
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
110122
back in time to old firmware versions. The WiPy can hold up to 3 different
111123
firmware versions, which are: the factory firmware plus 2 user updates.
112124

113-
After reset, if ``GP28`` is held high, the heart beat LED will start flashing
125+
After reset, if ``GP28`` is held high, the heartbeat LED will start flashing
114126
slowly, if after 3 seconds the pin is still being held high, the LED will start
115127
blinking a bit faster and the WiPy will select the previous user update to boot.
116128
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
134146
made during safe boot is not persistent, meaning that after the next normal reset,
135147
the latest firmware will run again.
136148

137-
The heart beat LED
149+
The heartbeat LED
138150
------------------
139151

140-
By default the heart beat LED flashes once every 4s to signal that the system is
152+
By default the heartbeat LED flashes once every 4s to signal that the system is
141153
alive. This can be overridden through the :mod:`wipy` module::
142154

143-
import wipy
144-
wipy.heartbeat(False)
155+
>>> import wipy
156+
>>> wipy.heartbeat(False)
145157

146158
There are currently 2 kinds of errors that you might see:
147159

148-
1. If the heart beat LED flashes quickly, then a Python script(eg ``main.py``)
160+
1. If the heartbeat LED flashes quickly, then a Python script(eg ``main.py``)
149161
has an error. Use the REPL to debug it.
150-
2. If the heart beat LED stays on, then there was a hard fault, you cannot
162+
2. If the heartbeat LED stays on, then there was a hard fault, you cannot
151163
recover from this, the only way out is to press the reset switch.
152164

‎docs/wipy/tutorial/blynk.rst‎

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

‎docs/wipy/tutorial/index.rst‎

Lines changed: 12 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,15 @@
33
WiPy tutorials and examples
44
===========================
55

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

‎docs/wipy/tutorial/intro.rst‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
Introduction to the WiPy
2+
========================
3+
4+
To get the most out of your WiPy, there are a few basic things to
5+
understand about how it works.
6+
7+
Caring for your WiPy and expansion board
8+
----------------------------------------
9+
10+
Because the WiPy/expansion board does not have a housing it needs a bit of care:
11+
12+
- Be gentle when plugging/unplugging the USB cable. Whilst the USB connector
13+
is well soldered and is relatively strong, if it breaks off it can be very
14+
difficult to fix.
15+
16+
- Static electricity can shock the components on the WiPy and destroy them.
17+
If you experience a lot of static electricity in your area (eg dry and cold
18+
climates), take extra care not to shock the WiPy. If your WiPy came
19+
in a ESD bag, then this bag is the best way to store and carry the
20+
pyboard as it will protect it agains static discharges.
21+
22+
As long as you take care of the hardware, you should be okay. It's almost
23+
impossible to break the software on the WiPy, so feel free to play around
24+
with writing code as much as you like. If the filesystem gets corrupt, see
25+
below on how to reset it. In the worst case you might need to do a safe boot,
26+
which is explained in detail :ref:`here <wipy_boot_modes>`.
27+
28+
Plugging into the expansion board and powering on
29+
-------------------------------------------------
30+
31+
The expansion board can power the WiPy via USB. The WiPy comes with a sticker
32+
on top of the RF shield tha labels all pins, and this should match the label
33+
numbers on the expansion board headers. When pluggin it in, the WiPy antenna
34+
will end up on top of the SD card connector of the expansion board. A video
35+
showing how to do this can be found `here <https://www.youtube.com/watch?v=47D9MZ9zFQw>`_.
36+
37+
Expansion board hardware guide
38+
------------------------------
39+
40+
The document explaining the hardware details of the expansion board can be found
41+
`here <https://github.com/wipy/wipy/blob/master/docs/User_manual_exp_board.pdf>`_.
42+
43+
Powering by an external power source
44+
------------------------------------
45+
46+
The WiPy can be powered by a battery or other external power source.
47+
48+
**Be sure to connect the positive lead of the power supply to VIN, and
49+
ground to GND. There is no polarity protection on the pyboard so you
50+
must be careful when connecting anything to VIN.**
51+
52+
- When powering via ``VIN``:
53+
54+
**The input voltage must be between 3.6V and 5.5V.**
55+
56+
- When powering via ``3V3``:
57+
58+
**The input volatge must be exactly 3V3, ripple free and from a supply capable
59+
of sourcing at least 300mA of current**
60+
61+
Performing firmware upgrades
62+
----------------------------
63+
64+
For detalied instructions see :ref:`OTA How-To <wipy_firmware_upgrade>`.

‎docs/wipy/tutorial/repl.rst‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
Getting a MicroPython REPL prompt
2+
=================================
3+
4+
REPL stands for Read Evaluate Print Loop, and is the name given to the
5+
interactive MicroPython prompt that you can access on the WiPy. Using
6+
the REPL is by far the easiest way to test out your code and run commands.
7+
You can use the REPL in addition to writing scripts in ``main.py``.
8+
9+
To use the REPL, you must connect to the WiPy either via :ref:`telnet <wipy_telnet>`,
10+
or with a USB to serial converter wired to the one the two UARTs on the
11+
WiPy. To enable REPL duplication on UART0 (the one accesible via the expansion board)
12+
do::
13+
14+
>>> from machine import UART
15+
>>> import os
16+
>>> uart = UART(0, 115200)
17+
>>> o.dupterm(uart)
18+
19+
Place this piece of code inside your `boot.py` so that it's done automatically after
20+
reset.
21+
22+
Windows
23+
-------
24+
25+
You need to install the pyboard driver to use the serial USB device.
26+
The driver is on the pyboard's USB flash drive, and is called ``pybcdc.inf``.
27+
28+
To install this driver you need to go to Device Manager
29+
for your computer, find the pyboard in the list of devices (it should have
30+
a warning sign next to it because it's not working yet), right click on
31+
the pyboard device, select Properties, then Install Driver. You need to
32+
then select the option to find the driver manually (don't use Windows auto update),
33+
navigate to the pyboard's USB drive, and select that. It should then install.
34+
After installing, go back to the Device Manager to find the installed pyboard,
35+
and see which COM port it is (eg COM4).
36+
More comprehensive instructions can be found in the
37+
`Guide for pyboard on Windows (PDF) <http://micropython.org/resources/Micro-Python-Windows-setup.pdf>`_.
38+
Please consult this guide if you are having problems installing the driver.
39+
40+
The best option is to download the free program PuTTY:
41+
`putty.exe <http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html>`_.
42+
43+
**In order to get to the telnet REPL:**
44+
45+
Using putty, select ``Telnet`` as connection type, leave the default port (23)
46+
and enter the IP address of your WiPy (192.168.1.1 when in ``WLAN.AP`` mode),
47+
then click open.
48+
49+
**In order to get to the REPL UART:**
50+
51+
Using your serial program you must connect to the COM port that you found in the
52+
previous step. With PuTTY, click on "Session" in the left-hand panel, then click
53+
the "Serial" radio button on the right, then enter you COM port (eg COM4) in the
54+
"Serial Line" box. Finally, click the "Open" button.
55+
56+
Mac OS X
57+
--------
58+
59+
Open a terminal and run::
60+
61+
$ telnet 192.168.1.1
62+
63+
or::
64+
65+
$ screen /dev/tty.usbmodem* 115200
66+
67+
When you are finished and want to exit screen, type CTRL-A CTRL-\\.
68+
69+
Linux
70+
-----
71+
72+
Open a terminal and run::
73+
74+
$ telnet 192.168.1.1
75+
76+
or::
77+
78+
$ screen /dev/ttyUSB0 115200
79+
80+
You can also try ``picocom`` or ``minicom`` instead of screen. You may have to
81+
use ``/dev/ttyUSB01`` or a higher number for ``ttyUSB``. And, you may need to give
82+
yourself the correct permissions to access this devices (eg group ``uucp`` or ``dialout``,
83+
or use sudo).
84+
85+
Using the REPL prompt
86+
---------------------
87+
88+
Now let's try running some MicroPython code directly on the WiPy.
89+
90+
With your serial program open (PuTTY, screen, picocom, etc) you may see a blank
91+
screen with a flashing cursor. Press Enter and you should be presented with a
92+
MicroPython prompt, i.e. ``>>>``. Let's make sure it is working with the obligatory test::
93+
94+
>>> print("hello WiPy!")
95+
hello WiPy!
96+
97+
In the above, you should not type in the ``>>>`` characters. They are there to
98+
indicate that you should type the text after it at the prompt. In the end, once
99+
you have entered the text ``print("hello pyboard!")`` and pressed Enter, the output
100+
on your screen should look like it does above.
101+
102+
If you already know some python you can now try some basic commands here.
103+
104+
If any of this is not working you can try either a hard reset or a soft reset;
105+
see below.
106+
107+
Go ahead and try typing in some other commands. For example::
108+
109+
>>> from machine import Pin
110+
>>> import wipy
111+
>>> wipy.heartbeat(False) # disable the heartbeat
112+
>>> led = Pin('GP25', mode=Pin.OUT)
113+
>>> led(1)
114+
>>> led(0)
115+
>>> led.toggle()
116+
>>> 1 + 2
117+
3
118+
>>> 4 // 2
119+
2
120+
>>> 20 * 'py'
121+
'pypypypypypypypypypypypypypypypypypypypy'
122+
123+
Resetting the board
124+
-------------------
125+
126+
If something goes wrong, you can reset the board in two ways. The first is to press CTRL-D
127+
at the MicroPython prompt, which performs a soft reset. You will see a message something like::
128+
129+
>>>
130+
PYB: soft reboot
131+
MicroPython v1.4.6-146-g1d8b5e5 on 2015-10-21; WiPy with CC3200
132+
Type "help()" for more information.
133+
>>>
134+
135+
If that isn't working you can perform a hard reset (turn-it-off-and-on-again) by pressing the
136+
RST switch (the small black button next to the heartbeat LED). During telnet, this will end
137+
your session, disconnecting whatever program that you used to connect to the WiPy.

0 commit comments

Comments
 (0)