docs: Several corrections to the classes in the machine module.

docs/library/machine.HeartBeat.rst

-.. _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()
-      ...

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

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()
 

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.
 

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
 ---------

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

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

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
     ------------
 

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 <https://github.com/wipy/wipy/tree/master/examples/blynk>`_ 
    and put it in '/flash/cert/'. Then do::

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 <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``
+
+See :ref:`network.server <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, so for instance
-if using the native unix ftp client, just after logging in::
+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
 ----------

docs/wipy/quickref.rst

@@ -88,9 +88,9 @@ See :ref:`machine.ADC <machine.ADC>`. ::
 UART (serial bus)
 -----------------
 
-See :ref:`machine.Pin <machine.Pin>` and :ref:`machine.UART <machine.UART>`. ::
+See :ref:`machine.UART <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 <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 <machine.SPI>`. ::
 I2C bus
 -------
 
-See :ref:`machine.Pin <machine.Pin>` and :ref:`machine.I2C <machine.I2C>`. ::
+See :ref:`machine.I2C <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 <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 <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`. ::