diff options
Diffstat (limited to 'docs/wipy/general.rst')
| -rw-r--r-- | docs/wipy/general.rst | 206 |
1 files changed, 205 insertions, 1 deletions
diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index 0991dbaea..f28edb4e4 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -53,7 +53,7 @@ which is stored within the external serial flash memory. If a micro SD card 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. +``/flash`` file system. On boot up, the current directory is ``/flash``. The file system is accessible via the native FTP server running in the WiPy. Open your FTP client of choice and connect to: @@ -179,3 +179,207 @@ Details on sleep modes * ``machine.sleep()``: 950uA (in WLAN STA mode). Wake sources are ``Pin``, ``RTC`` and ``WLAN`` * ``machine.deepsleep()``: ~350uA. Wake sources are ``Pin`` and ``RTC``. + +Additional details for machine.Pin +---------------------------------- + +On the WiPy board the pins are identified by their string id:: + + 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 = Pin('GP10', mode=Pin.IN, pull=Pin.PULL_DOWN) + pin_int.irq(trigger=Pin.IRQ_RISING, handler=pincb) + # the callback can be triggered manually + pin_int.irq()() + # to disable the callback + pin_int.irq().disable() + +Now every time a falling edge is seen on the gpio pin, the callback will be +executed. Caution: mechanical push buttons have "bounce" and pushing or +releasing a switch will often generate multiple edges. +See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed +explanation, along with various techniques for debouncing. + +All pin objects go through the pin mapper to come up with one of the +gpio pins. + +For the ``drive`` parameter the strengths are: + + - ``Pin.LOW_POWER`` - 2mA drive capability. + - ``Pin.MED_POWER`` - 4mA drive capability. + - ``Pin.HIGH_POWER`` - 6mA drive capability. + +For the ``alt`` parameter please refer to the pinout and alternate functions +table at <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ +for the specific alternate functions that each pin supports. + +For interrupts, the ``priority`` can take values in the range 1-7. And the +``wake`` parameter has the following properties: + + - If ``wake_from=machine.Sleep.ACTIVE`` any pin can wake the board. + - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``, + ``GP11``, GP17`` or ``GP24`` can wake the board. Note that only 1 + of this pins can be enabled as a wake source at the same time, so, only + the last enabled pin as a ``machine.Sleep.SUSPENDED`` wake source will have effect. + - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``, + ``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the + 6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time. + +Additional Pin methods: + +.. method:: machine.Pin.alt_list() + + Returns a list of the alternate functions supported by the pin. List items are + a tuple of the form: ``('ALT_FUN_NAME', ALT_FUN_INDEX)`` + +Additional details for machine.I2C +---------------------------------- + +On the WiPy there is a single hardware I2C peripheral, identified by "0". By +default this is the peripheral that is used when constructing an I2C instance. +The default pins are GP23 for SCL and GP13 for SDA, and one can create the +default I2C peripheral simply by doing:: + + i2c = machine.I2C() + +The pins and frequency can be specified as:: + + i2c = machine.I2C(freq=400000, scl='GP23', sda='GP13') + +Only certain pins can be used as SCL/SDA. Please refer to the pinout for further +information. + +Known issues +------------ + +Incompatible way to create SSL sockets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SSL sockets need to be created the following way before wrapping them with. +``ssl.wrap_socket``:: + + import socket + import ssl + s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) + ss = ssl.wrap_socket(s) + +Certificates must be used in order to validate the other side of the connection, and also to +authenticate ourselves with the other end. Such certificates must be stored as files using the +FTP server, and they must be placed in specific paths with specific names. + +- The certificate to validate the other side goes in: **'/flash/cert/ca.pem'** +- 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:: + + import socket + import ssl + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) + ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem') + ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1]) + +Incompatibilities in uhashlib module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Due to hardware implementation details of the WiPy, data must be buffered before being +digested, which would make it impossible to calculate the hash of big blocks of data that +do not fit in RAM. In this case, since most likely the total size of the data is known +in advance, the size can be passed to the constructor and hence the HASH hardware engine +of the WiPy can be properly initialized without needing buffering. If ``block_size`` is +to be given, an initial chunk of ``data`` must be passed as well. **When using this extension, +care must be taken to make sure that the length of all intermediate chunks (including the +initial one) is a multiple of 4 bytes.** The last chunk may be of any length. + +Example:: + + hash = uhashlib.sha1('abcd1234', 1001) # length of the initial piece is multiple of 4 bytes + hash.update('1234') # also multiple of 4 bytes + ... + hash.update('12345') # last chunk may be of any length + hash.digest() + +Unrelated function in machine module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. function:: main(filename) + + Set the filename of the main script to run after boot.py is finished. If + this function is not called then the default file main.py will be executed. + + It only makes sense to call this function from within boot.py. + +Adhoc way to control telnet/FTP server via network module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +Example:: + + import network + server = network.Server() + server.deinit() # disable the server + # enable the server again with new settings + server.init(login=('user', 'password'), timeout=600) + +.. class:: network.Server(id, ...) + + Create a server instance, see ``init`` for parameters of initialization. + +.. method:: server.init(\*, login=('micro', 'python'), timeout=300) + + Init (and effectively start the server). Optionally a new ``user``, ``password`` + and ``timeout`` (in seconds) can be passed. + +.. method:: server.deinit() + + Stop the server + +.. method:: server.timeout([timeout_in_seconds]) + + Get or set the server timeout. + +.. method:: server.isrunning() + + Returns ``True`` if the server is running, ``False`` otherwise. + +Adhoc VFS-like support +~~~~~~~~~~~~~~~~~~~~~~ + +WiPy doesn't implement full MicroPython VFS support, instead following +functions are defined in ``uos`` module: + +.. function:: mount(block_device, mount_point, \*, readonly=False) + + Mounts a block device (like an ``SD`` object) in the specified mount + point. Example:: + + os.mount(sd, '/sd') + +.. function:: unmount(path) + + Unmounts a previously mounted block device from the given path. + +.. function:: mkfs(block_device or path) + + Formats the specified path, must be either ``/flash`` or ``/sd``. + A block device can also be passed like an ``SD`` object before + being mounted. + |