From ceb169008d93165d461a9ab1b9bb5e9c85d03949 Mon Sep 17 00:00:00 2001 From: danicampora Date: Tue, 20 Oct 2015 16:24:25 +0200 Subject: [PATCH] docs: Several corrections to the classes in the machine module. --- docs/library/machine.HeartBeat.rst | 47 ---------------------------- docs/library/machine.Pin.rst | 9 ++++-- docs/library/machine.SD.rst | 9 +++--- docs/library/machine.Timer.rst | 19 +++++++----- docs/library/machine.UART.rst | 2 +- docs/library/machine.WDT.rst | 3 +- docs/library/machine.rst | 1 - docs/library/network.rst | 4 +++ docs/library/ussl.rst | 5 +++ docs/wipy/general.rst | 49 +++++++++++++++++++----------- docs/wipy/quickref.rst | 16 +++++----- 11 files changed, 72 insertions(+), 92 deletions(-) delete mode 100644 docs/library/machine.HeartBeat.rst diff --git a/docs/library/machine.HeartBeat.rst b/docs/library/machine.HeartBeat.rst deleted file mode 100644 index 033d7311fb..0000000000 --- a/docs/library/machine.HeartBeat.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _machine.HeartBeat: - -class HeartBeat -- heart beat LED -================================= - -The HeartBeat class controls the heart beat led which by default -flashes once every 5s. The user can disable the HeartBeat and then -is free to control this LED manually through GP25 using the Pin -class. The GP25 can also be remapped as a PWM output, an this -can be used to control the light intesity of the heart beat LED. - -Example usage:: - - hb = machine.HeartBeat() - hb.disable() # disable the heart beat - hb.enable() # enable the heart beat - -Constructors ------------- - -.. class:: machine.HeartBeat() - - Create a HeartBeat object. - -Methods -------- - -.. method:: heartbeat.enable() - - Enable the heart beat. The LED will flash once every 5 seconds. - -.. method:: heartbeat.disable() - - Disable the heart beat. The LED can then be controlled manually. - - Example:: - - from machine import HeartBeat - from machine import Pin - - # disable the heart beat - HeartBeat().disable() - # init GP25 as output - led = Pin('GP25', mode=Pin.OUT) - # toggle the led - led.toggle() - ... diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index f7b783c191..452e2234e3 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -13,15 +13,18 @@ Usage Model: Board pins are identified by their string id:: - g = machine.Pin('GP9', mode=machine.Pin.OUT, pull=None, drive=machine.Pin.MED_POWER, alt=-1) + from machine import Pin + g = machine.Pin('GP9', mode=Pin.OUT, pull=None, drive=Pin.MED_POWER, alt=-1) You can also configure the Pin to generate interrupts. For instance:: + from machine import Pin + def pincb(pin): print(pin.id()) - pin_int = machine.Pin('GP10', mode=Pin.IN, pull=machine.Pin.PULL_DOWN) - pin_int.irq(mode=machine.Pin.IRQ_RISING, handler=pincb) + pin_int = Pin('GP10', mode=Pin.IN, pull=Pin.PULL_DOWN) + pin_int.irq(mode=Pin.IRQ_RISING, handler=pincb) # the callback can be triggered manually pin_int.irq()() # to disable the callback diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst index 19d8d655bd..da60121d07 100644 --- a/docs/library/machine.SD.rst +++ b/docs/library/machine.SD.rst @@ -26,16 +26,15 @@ Constructors .. class:: machine.SD(id,... ) - Create a SD card object. See init for parameters if initialization. + Create a SD card object. See ``init()`` for parameters if initialization. Methods ------- -.. method:: sd.init(id, pins=('GP10', 'GP11', 'GP15')) +.. method:: sd.init(id=0, pins=('GP10', 'GP11', 'GP15')) - Enable the SD card. - In order to initalize the card, give it a 3-tuple ``(clk_pin, cmd_pin, dat0_pin)`` - ID defaults to zero. + Enable the SD card. In order to initalize the card, give it a 3-tuple: + ``(clk_pin, cmd_pin, dat0_pin)``. .. method:: sd.deinit() diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst index 4814da8603..5d357ca079 100644 --- a/docs/library/machine.Timer.rst +++ b/docs/library/machine.Timer.rst @@ -19,13 +19,15 @@ class Timer -- control internal timers Example usage to toggle an LED at a fixed frequency:: - tim = machine.Timer(4) # create a timer object using timer 4 - tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode - tim_ch = tim.channel(Timer.A, freq=2) # configure channel A at a frequency of 2Hz - tim_ch.callback(handler=lambda t:led.toggle()) # toggle a LED on every cycle of the timer + from machine import Timer + tim = Timer(4) # create a timer object using timer 4 + tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode + tim_ch = tim.channel(Timer.A, freq=2) # configure channel A at a frequency of 2Hz + tim_ch.callback(handler=lambda t:led.toggle()) # toggle a LED on every cycle of the timer Example using named function for the callback:: + from machine import Timer tim = Timer(1, mode=Timer.PERIODIC) tim_a = tim.channel(Timer.A, freq=1000) @@ -39,8 +41,9 @@ class Timer -- control internal timers Further examples:: - tim1 = machine.Timer(2, mode=Timer.EVENT_COUNT) # initialize it capture mode - tim2 = machine.Timer(1, mode=Timer.PWM) # initialize it in PWM mode + from machine import Timer + tim1 = Timer(2, mode=Timer.EVENT_COUNT) # initialize it capture mode + tim2 = Timer(1, mode=Timer.PWM) # initialize it in PWM mode tim_ch = tim1.channel(Timer.A, freq=1, polarity=Timer.POSITIVE) # start the event counter with a frequency of 1Hz and triggered by positive edges tim_ch = tim2.channel(Timer.B, freq=10000, duty_cycle=50) # start the PWM on channel B with a 50% duty cycle tim_ch.time() # get the current time in usec (can also be set) @@ -54,8 +57,8 @@ class Timer -- control internal timers .. note:: - Memory can't be allocated during a callback (an interrupt) and so - exceptions raised within a callback don't give much information. See + Memory can't be allocated inside irq handlers (an interrupt) and so + exceptions raised within a handler don't give much information. See :func:`micropython.alloc_emergency_exception_buf` for how to get around this limitation. diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index 034492717c..732b30788d 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -155,7 +155,7 @@ Methods This means that when the handler function is called there will be between 1 to 8 characters waiting. - Returns a irq object. + Returns an irq object. Constants --------- diff --git a/docs/library/machine.WDT.rst b/docs/library/machine.WDT.rst index 9ce0a96ac3..dca74f70f6 100644 --- a/docs/library/machine.WDT.rst +++ b/docs/library/machine.WDT.rst @@ -10,7 +10,8 @@ watchdog periodically to prevent it from expiring and resetting the system. Example usage:: - wdt = machine.WDT(timeout=2000) # enable with a timeout of 2s + from machine import WDT + wdt = WDT(timeout=2000) # enable it with a timeout of 2s wdt.feed() Constructors diff --git a/docs/library/machine.rst b/docs/library/machine.rst index f94454359b..c78b7c1b67 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -121,7 +121,6 @@ Classes :maxdepth: 1 machine.ADC.rst - machine.HeartBeat.rst machine.I2C.rst machine.Pin.rst machine.RTC.rst diff --git a/docs/library/network.rst b/docs/library/network.rst index 0b9acf6423..8522ee2948 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -34,6 +34,10 @@ For example:: class server ============ + The server class controls the behaviour and the configuration of the FTP and telnet + services running on the WiPy. Any changes performed using this class' methods will + affect both. + Constructors ------------ diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst index 9e97fac502..ce9fd01e27 100644 --- a/docs/library/ussl.rst +++ b/docs/library/ussl.rst @@ -31,6 +31,11 @@ Functions - The certificate to authenticate ourselves goes in: **'/flash/cert/cert.pem'** - The key for our own certificate goes in: **'/flash/cert/private.key'** + .. note:: + + When these files are stored, they are placed inside the internal **hidden** file system + (just like firmware updates), and therefore they are never visible. + For instance to connect to the Blynk servers using certificates, take the file ``ca.pem`` located in the `blynk examples folder `_ and put it in '/flash/cert/'. Then do:: diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index e52fcc9266..caee24a09e 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -18,11 +18,9 @@ Before applying power The GPIO pins of the WiPy are NOT 5V tolerant, connecting them to voltages higer than 3.6V will cause irreparable damage to the board. ADC pins, when configured - in analog mode cannot withstand volatges above 1.8V. Keep these considerations in + in analog mode cannot withstand voltages above 1.8V. Keep these considerations in mind when wiring your electronics. - - WLAN default behaviour ---------------------- @@ -33,29 +31,43 @@ 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`` -Local file system and SD card ------------------------------ +Telnet REPL +----------- + +Linux stock telnet works like a charm (also on OSX), but other tools like putty +work quite too. The default credentials are: **user:** ``micro``, **password:** ``python``. +See :ref:`network.server ` for info on how to change the defaults. +For instance, on a linux shell (when connected to the WiPy in AP mode):: + + $ telnet 192.168.1.1 + +Local file system and FTP access +-------------------------------- There is a small internal file system (a drive) on the WiPy, called ``/flash``, which is stored within the external serial flash memory. If a micro SD card -is hooked-up and enabled, it is available as ``/sd``. +is hooked-up and mounted, it will be available as well. -When the WiPy boots up, it always boots from the ``boot.py`` located in the -``/flash`` file system. If during the boot process the SD card is enabled and -it's selected as the current drive then the WiPy will try to execute ``main.py`` -that should be located in the SD card. +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. Open your FTP client of choice and connect to: -``ftp://192.168.1.1``, ``user: micro``, ``password: python`` +**url:** ``ftp://192.168.1.1``, **user:** ``micro``, **password:** ``python`` -The FTP server on the WiPy doesn't support active mode, only passive, so for instance -if using the native unix ftp client, just after logging in:: +See :ref:`network.server ` for info on how to change the defaults. +The recommended clients are: Linux stock FTP (also in OSX), Filezilla and FireFTP. +For example, on a linux shell:: + + $ ftp 192.168.1.1 + +The FTP server on the WiPy doesn't support active mode, only passive, therefore, +if using the native unix ftp client, just after logging in do:: ftp> passive -Besides that, the FTP server only supports onw data connection at a time. Check out +Besides that, the FTP server only supports one data connection at a time. Check out the Filezilla settings section below for more info. FileZilla settings @@ -74,16 +86,17 @@ Upgrading the firmware Over The Air OTA software updates can be performed through the FTP server. Upload the ``mcuimg.bin`` file to: ``/flash/sys/mcuimg.bin`` it will take around 6s. You won't see the file being stored -inside ``/flash/sys/`` because it's actually saved bypassing the user file system, but rest -assured that it was successfully transferred, and it has been signed with a MD5 checksum to -verify its integrity. Now, reset the MCU by pressing the switch on the board, or by typing:: +inside ``/flash/sys/`` because it's actually saved bypassing the user file system, so it +ends up inside the internal **hidden** file system, but rest assured that it was successfully +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() 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. +read the **release notes** before. Boot modes ---------- diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst index 4ecffffe38..e473017e83 100644 --- a/docs/wipy/quickref.rst +++ b/docs/wipy/quickref.rst @@ -88,9 +88,9 @@ See :ref:`machine.ADC `. :: UART (serial bus) ----------------- -See :ref:`machine.Pin ` and :ref:`machine.UART `. :: +See :ref:`machine.UART `. :: - from machine import Pin, UART + from machine import UART uart = UART(0, baudrate=9600) uart.write('hello') uart.read(5) # read up to 5 bytes @@ -100,7 +100,7 @@ SPI bus See :ref:`machine.SPI `. :: - from machine SPI + from machine import SPI # configure the SPI master @ 2MHz spi = SPI(0, SPI.MASTER, baudrate=200000, polarity=0, phase=0) @@ -112,9 +112,9 @@ See :ref:`machine.SPI `. :: I2C bus ------- -See :ref:`machine.Pin ` and :ref:`machine.I2C `. :: +See :ref:`machine.I2C `. :: - from machine import Pin, I2C + from machine import I2C # configure the I2C bus i2c = I2C(0, I2C.MASTER, baudrate=100000) i2c.scan() # returns list of slave addresses @@ -203,7 +203,7 @@ Telnet and FTP server See :ref:`network.server ` :: - from network import network + from network import server # init with new user, pass word and seconds timeout server = server.init(login=('user', 'password'), timeout=60) @@ -211,8 +211,8 @@ See :ref:`network.server ` :: server.timeout() # get the timeout server.isrunning() # check wether the server is running or not -HeartBeat LED -------------- +Heart beat LED +-------------- See :mod:`wipy`. ::