From 109b363ddc1a83ec35511bde0eea8bb8a0ec206b Mon Sep 17 00:00:00 2001 From: danicampora Date: Wed, 21 Oct 2015 14:58:04 +0200 Subject: [PATCH] docs/wipy: Add more tutorials and examples. --- docs/wipy/general.rst | 40 ++++++---- docs/wipy/tutorial/blynk.rst | 19 +++++ docs/wipy/tutorial/index.rst | 33 +++------ docs/wipy/tutorial/intro.rst | 64 ++++++++++++++++ docs/wipy/tutorial/repl.rst | 137 +++++++++++++++++++++++++++++++++++ docs/wipy/tutorial/reset.rst | 53 ++++++++++++++ docs/wipy/tutorial/wlan.rst | 61 ++++++++++++++++ 7 files changed, 370 insertions(+), 37 deletions(-) create mode 100644 docs/wipy/tutorial/blynk.rst create mode 100644 docs/wipy/tutorial/intro.rst create mode 100644 docs/wipy/tutorial/repl.rst create mode 100644 docs/wipy/tutorial/reset.rst create mode 100644 docs/wipy/tutorial/wlan.rst diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index caee24a09e..d8c02de68d 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -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 `_, 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. diff --git a/docs/wipy/tutorial/blynk.rst b/docs/wipy/tutorial/blynk.rst new file mode 100644 index 0000000000..a804c67192 --- /dev/null +++ b/docs/wipy/tutorial/blynk.rst @@ -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 ` for instructions. + +1. Get the `Blynk library `_ and put it in ``/flash/lib/`` via FTP. +2. Get the `Blynk examples `_ 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') diff --git a/docs/wipy/tutorial/index.rst b/docs/wipy/tutorial/index.rst index 751d9d7976..90523d0dce 100644 --- a/docs/wipy/tutorial/index.rst +++ b/docs/wipy/tutorial/index.rst @@ -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 `. -For detalied instructions see :ref:`OTA How-To `. - -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 `. - -1. Get the `Blynk library `_ and put it in ``/flash/lib/`` via FTP. -2. Get the `Blynk examples `_ 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 diff --git a/docs/wipy/tutorial/intro.rst b/docs/wipy/tutorial/intro.rst new file mode 100644 index 0000000000..a8503302c8 --- /dev/null +++ b/docs/wipy/tutorial/intro.rst @@ -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 `. + +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 `_. + +Expansion board hardware guide +------------------------------ + +The document explaining the hardware details of the expansion board can be found +`here `_. + +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 `. diff --git a/docs/wipy/tutorial/repl.rst b/docs/wipy/tutorial/repl.rst new file mode 100644 index 0000000000..3ff602aaeb --- /dev/null +++ b/docs/wipy/tutorial/repl.rst @@ -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 `, +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) `_. +Please consult this guide if you are having problems installing the driver. + +The best option is to download the free program PuTTY: +`putty.exe `_. + +**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. diff --git a/docs/wipy/tutorial/reset.rst b/docs/wipy/tutorial/reset.rst new file mode 100644 index 0000000000..970f8d1ddc --- /dev/null +++ b/docs/wipy/tutorial/reset.rst @@ -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 `. + +To boot in safe mode, follow the detailed instructions described :ref:`here `. + +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. diff --git a/docs/wipy/tutorial/wlan.rst b/docs/wipy/tutorial/wlan.rst new file mode 100644 index 0000000000..15a9bbefe8 --- /dev/null +++ b/docs/wipy/tutorial/wlan.rst @@ -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.