diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/esp8266/general.rst | 40 | ||||
| -rw-r--r-- | docs/esp8266/quickref.rst | 11 | ||||
| -rw-r--r-- | docs/library/network.rst | 38 | ||||
| -rw-r--r-- | docs/library/pyb.Accel.rst | 1 | ||||
| -rw-r--r-- | docs/library/pyb.CAN.rst | 1 | ||||
| -rw-r--r-- | docs/library/pyb.LCD.rst | 1 | ||||
| -rw-r--r-- | docs/library/pyb.Switch.rst | 1 | ||||
| -rw-r--r-- | docs/library/pyb.USB_HID.rst | 1 | ||||
| -rw-r--r-- | docs/library/pyb.USB_VCP.rst | 1 | ||||
| -rw-r--r-- | docs/library/ure.rst | 2 | ||||
| -rw-r--r-- | docs/library/uselect.rst | 10 | ||||
| -rw-r--r-- | docs/library/usocket.rst | 59 | ||||
| -rw-r--r-- | docs/library/ussl.rst | 14 | ||||
| -rw-r--r-- | docs/pyboard/quickref.rst | 54 | ||||
| -rw-r--r-- | docs/pyboard/tutorial/leds.rst | 8 | ||||
| -rw-r--r-- | docs/reference/isr_rules.rst | 2 |
16 files changed, 207 insertions, 37 deletions
diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst index e23acb469..96a454532 100644 --- a/docs/esp8266/general.rst +++ b/docs/esp8266/general.rst @@ -145,3 +145,43 @@ or by an exeption, for example using try/finally:: # Use sock finally: sock.close() + + +SSL/TLS limitations +~~~~~~~~~~~~~~~~~~~ + +ESP8266 uses `axTLS <http://axtls.sourceforge.net/>`_ library, which is one +of the smallest TLS libraries with the compatible licensing. However, it +also has some known issues/limitations: + +1. No support for Diffie-Hellman (DH) key exchange and Elliptic-curve + cryptography (ECC). This means it can't work with sites which force + the use of these features (it works ok with classic RSA certifactes). +2. Half-duplex communication nature. axTLS uses a single buffer for both + sending and receiving, which leads to considerable memory saving and + works well with protocols like HTTP. But there may be problems with + protocols which don't follow classic request-response model. + +Besides axTLS own limitations, the configuration used for MicroPython is +highly optimized for code size, which leads to additional limitations +(these may be lifted in the future): + +3. Optimized RSA algorithms are not enabled, which may lead to slow + SSL handshakes. +4. Stored sessions are not supported (may allow faster repeated connections + to the same site in some circumstances). + +Besides axTLS specific limitations described above, there's another generic +limitation with usage of TLS on the low-memory devices: + +5. The TLS standard specifies the maximum length of the TLS record (unit + of TLS communication, the entire record must be buffered before it can + be processed) as 16KB. That's almost half of the available ESP8266 memory, + and inside a more or less advanced application would be hard to allocate + due to memory fragmentation issues. As a compromise, a smaller buffer is + used, with the idea that the most interesting usage for SSL would be + accessing various REST APIs, which usually require much smaller messages. + The buffers size is on the order of 5KB, and is adjusted from time to + time, taking as a reference being able to access https://google.com . + The smaller buffer hower means that some sites can't be accessed using + it, and it's not possible to stream large amounts of data. diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst index ccf6365c8..c510e4064 100644 --- a/docs/esp8266/quickref.rst +++ b/docs/esp8266/quickref.rst @@ -223,6 +223,17 @@ and is accessed via the :ref:`machine.I2C <machine.I2C>` class:: buf = bytearray(10) # create a buffer with 10 bytes i2c.writeto(0x3a, buf) # write the given buffer to the slave +Real time clock (RTC) +--------------------- + +See :ref:`machine.RTC <machine.RTC>` :: + + from machine import RTC + + rtc = RTC() + rtc.datetime((2017, 8, 23, 1, 12, 48, 0, 0)) # set a specific date and time + rtc.datetime() # get date and time + Deep-sleep mode --------------- diff --git a/docs/library/network.rst b/docs/library/network.rst index def6bee74..99a7c242c 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -72,8 +72,7 @@ parameter should be `id`. connection parameters. For various medium types, there are different sets of predefined/recommended parameters, among them: - * WiFi: *bssid* keyword to connect by BSSID (MAC address) instead - of access point name + * WiFi: *bssid* keyword to connect to a specific BSSID (MAC address) .. method:: disconnect() @@ -225,7 +224,9 @@ parameter should be `id`. ============== This class allows you to control WIZnet5x00 Ethernet adaptors based on - the W5200 and W5500 chipsets (only W5200 tested). + the W5200 and W5500 chipsets. The particular chipset that is supported + by the firmware is selected at compile-time via the MICROPY_PY_WIZNET5K + option. Example usage:: @@ -269,6 +270,11 @@ parameter should be `id`. Methods ------- + .. method:: wiznet5k.isconnected() + + Returns ``True`` if the physical Ethernet link is connected and up. + Returns ``False`` otherwise. + .. method:: wiznet5k.ifconfig([(ip, subnet, gateway, dns)]) Get/set IP address, subnet mask, gateway and DNS. @@ -333,9 +339,12 @@ parameter should be `id`. argument is passed. Otherwise, query current state if no argument is provided. Most other methods require active interface. - .. method:: wlan.connect(ssid, password) + .. method:: wlan.connect(ssid=None, password=None, \*, bssid=None) Connect to the specified wireless network, using the specified password. + If *bssid* is given then the connection will be restricted to the + access-point with that MAC address (the *ssid* must also be specified + in this case). .. method:: wlan.disconnect() @@ -413,16 +422,17 @@ parameter should be `id`. Following are commonly supported parameters (availability of a specific parameter depends on network technology type, driver, and `MicroPython port`). - ========= =========== - Parameter Description - ========= =========== - mac MAC address (bytes) - essid WiFi access point name (string) - channel WiFi channel (integer) - hidden Whether ESSID is hidden (boolean) - authmode Authentication mode supported (enumeration, see module constants) - password Access password (string) - ========= =========== + ============= =========== + Parameter Description + ============= =========== + mac MAC address (bytes) + essid WiFi access point name (string) + channel WiFi channel (integer) + hidden Whether ESSID is hidden (boolean) + authmode Authentication mode supported (enumeration, see module constants) + password Access password (string) + dhcp_hostname The DHCP hostname to use + ============= =========== diff --git a/docs/library/pyb.Accel.rst b/docs/library/pyb.Accel.rst index 061996485..9ade5c5c8 100644 --- a/docs/library/pyb.Accel.rst +++ b/docs/library/pyb.Accel.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.Accel: class Accel -- accelerometer control ==================================== diff --git a/docs/library/pyb.CAN.rst b/docs/library/pyb.CAN.rst index 9e71f12b0..232d04d96 100644 --- a/docs/library/pyb.CAN.rst +++ b/docs/library/pyb.CAN.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.CAN: class CAN -- controller area network communication bus ====================================================== diff --git a/docs/library/pyb.LCD.rst b/docs/library/pyb.LCD.rst index 83cf890b6..5ab127edc 100644 --- a/docs/library/pyb.LCD.rst +++ b/docs/library/pyb.LCD.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.LCD: class LCD -- LCD control for the LCD touch-sensor pyskin ======================================================== diff --git a/docs/library/pyb.Switch.rst b/docs/library/pyb.Switch.rst index 0d5dc63b7..e5ab6bd84 100644 --- a/docs/library/pyb.Switch.rst +++ b/docs/library/pyb.Switch.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.Switch: class Switch -- switch object ============================= diff --git a/docs/library/pyb.USB_HID.rst b/docs/library/pyb.USB_HID.rst index 7d17c3099..702704435 100644 --- a/docs/library/pyb.USB_HID.rst +++ b/docs/library/pyb.USB_HID.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.USB_HID: class USB_HID -- USB Human Interface Device (HID) ================================================= diff --git a/docs/library/pyb.USB_VCP.rst b/docs/library/pyb.USB_VCP.rst index 4c4fe4516..80cc40cdd 100644 --- a/docs/library/pyb.USB_VCP.rst +++ b/docs/library/pyb.USB_VCP.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.USB_VCP: class USB_VCP -- USB virtual comm port ====================================== diff --git a/docs/library/ure.rst b/docs/library/ure.rst index 67f4f54a1..ebae1db5f 100644 --- a/docs/library/ure.rst +++ b/docs/library/ure.rst @@ -34,6 +34,8 @@ Supported operators are: ``'+?'`` +``'|'`` + ``'()'`` Grouping. Each group is capturing (a substring it captures can be accessed with `match.group()` method). diff --git a/docs/library/uselect.rst b/docs/library/uselect.rst index e330207db..beffce69a 100644 --- a/docs/library/uselect.rst +++ b/docs/library/uselect.rst @@ -66,12 +66,18 @@ Methods Tuples returned may contain more than 2 elements as described above. -.. method:: poll.ipoll([timeout]) +.. method:: poll.ipoll(timeout=-1, flags=0) Like :meth:`poll.poll`, but instead returns an iterator which yields - callee-owned tuples. This function provides efficient, allocation-free + `callee-owned tuples`. This function provides efficient, allocation-free way to poll on streams. + If *flags* is 1, one-shot behavior for events is employed: streams for + which events happened, event mask will be automatically reset (equivalent + to ``poll.modify(obj, 0)``), so new events for such a stream won't be + processed until new mask is set with `poll.modify()`. This behavior is + useful for asynchronous I/O schedulers. + .. admonition:: Difference to CPython :class: attention diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index dfdcd68bc..fab05b652 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -68,7 +68,16 @@ Functions .. function:: socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP) - Create a new socket using the given address family, socket type and protocol number. + Create a new socket using the given address family, socket type and + protocol number. Note that specifying *proto* in most cases is not + required (and not recommended, as some MicroPython ports may omit + ``IPPROTO_*`` constants). Instead, *type* argument will select needed + protocol automatically:: + + # Create STREAM TCP socket + socket(AF_INET, SOCK_STREAM) + # Create DGRAM UDP socket + socket(AF_INET, SOCK_DGRAM) .. function:: getaddrinfo(host, port) @@ -80,8 +89,8 @@ Functions The following example shows how to connect to a given url:: - s = socket.socket() - s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1]) + s = usocket.socket() + s.connect(usocket.getaddrinfo('www.micropython.org', 80)[0][-1]) .. admonition:: Difference to CPython :class: attention @@ -96,13 +105,29 @@ Functions from an exception object). The use of negative values is a provisional detail which may change in the future. +.. function:: inet_ntop(af, bin_addr) + + Convert a binary network address *bin_addr* of the given address family *af* + to a textual representation:: + + >>> usocket.inet_ntop(usocket.AF_INET, b"\x7f\0\0\1") + '127.0.0.1' + +.. function:: inet_pton(af, txt_addr) + + Convert a textual network address *txt_addr* of the given address family *af* + to a binary representation:: + + >>> usocket.inet_pton(usocket.AF_INET, "1.2.3.4") + b'\x01\x02\x03\x04' + Constants --------- .. data:: AF_INET AF_INET6 - Address family types. Availability depends on a particular board. + Address family types. Availability depends on a particular `MicroPython port`. .. data:: SOCK_STREAM SOCK_DGRAM @@ -112,7 +137,11 @@ Constants .. data:: IPPROTO_UDP IPPROTO_TCP - IP protocol numbers. + IP protocol numbers. Availability depends on a particular `MicroPython port`. + Note that you don't need to specify these in a call to `usocket.socket()`, + because `SOCK_STREAM` socket type automatically selects `IPPROTO_TCP`, and + `SOCK_DGRAM` - `IPPROTO_UDP`. Thus, the only real use of these constants + is as an argument to `setsockopt()`. .. data:: usocket.SOL_* @@ -208,12 +237,30 @@ Methods .. method:: socket.settimeout(value) + **Note**: Not every port supports this method, see below. + Set a timeout on blocking socket operations. The value argument can be a nonnegative floating point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations will raise an `OSError` exception if the timeout period value has elapsed before the operation has completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket is put in blocking mode. + Not every `MicroPython port` supports this method. A more portable and + generic solution is to use `uselect.poll` object. This allows to wait on + multiple objects at the same time (and not just on sockets, but on generic + stream objects which support polling). Example:: + + # Instead of: + s.settimeout(1.0) # time in seconds + s.read(10) # may timeout + + # Use: + poller = uselect.poll() + poller.register(s, uselect.POLLIN) + res = poller.poll(1000) # time in milliseconds + if not res: + # s is still not ready for input, i.e. operation timed out + .. admonition:: Difference to CPython :class: attention @@ -281,7 +328,7 @@ Methods Return value: number of bytes written. -.. exception:: socket.error +.. exception:: usocket.error MicroPython does NOT have this exception. diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst index c71b283cc..3ec609f67 100644 --- a/docs/library/ussl.rst +++ b/docs/library/ussl.rst @@ -13,7 +13,7 @@ facilities for network sockets, both client-side and server-side. Functions --------- -.. function:: ssl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None) +.. function:: ussl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None) Takes a stream *sock* (usually usocket.socket instance of ``SOCK_STREAM`` type), and returns an instance of ssl.SSLSocket, which wraps the underlying stream in @@ -23,12 +23,12 @@ Functions server-side SSL socket should be created from a normal socket returned from `accept()` on a non-SSL listening server socket. - Depending on the underlying module implementation for a particular board, - some or all keyword arguments above may be not supported. + Depending on the underlying module implementation in a particular + `MicroPython port`, some or all keyword arguments above may be not supported. .. warning:: - Some implementations of ``ssl`` module do NOT validate server certificates, + Some implementations of ``ussl`` module do NOT validate server certificates, which makes an SSL connection established prone to man-in-the-middle attacks. Exceptions @@ -41,8 +41,8 @@ Exceptions Constants --------- -.. data:: ssl.CERT_NONE - ssl.CERT_OPTIONAL - ssl.CERT_REQUIRED +.. data:: ussl.CERT_NONE + ussl.CERT_OPTIONAL + ussl.CERT_REQUIRED Supported values for *cert_reqs* parameter. diff --git a/docs/pyboard/quickref.rst b/docs/pyboard/quickref.rst index 5690dddb0..48798aad3 100644 --- a/docs/pyboard/quickref.rst +++ b/docs/pyboard/quickref.rst @@ -39,17 +39,32 @@ Use the :mod:`time <utime>` module:: start = time.ticks_ms() # get value of millisecond counter delta = time.ticks_diff(time.ticks_ms(), start) # compute time difference -LEDs ----- +Internal LEDs +------------- See :ref:`pyb.LED <pyb.LED>`. :: from pyb import LED - led = LED(1) # red led + led = LED(1) # 1=red, 2=green, 3=yellow, 4=blue led.toggle() led.on() led.off() + + # LEDs 3 and 4 support PWM intensity (0-255) + LED(4).intensity() # get intensity + LED(4).intensity(128) # set intensity to half + +Internal switch +--------------- + +See :ref:`pyb.Switch <pyb.Switch>`. :: + + from pyb import Switch + + sw = Switch() + sw.value() # returns True or False + sw.callback(lambda: pyb.LED(1).toggle()) Pins and GPIO ------------- @@ -99,6 +114,17 @@ See :ref:`pyb.Timer <pyb.Timer>`. :: tim.freq(0.5) # 0.5 Hz tim.callback(lambda t: pyb.LED(1).toggle()) +RTC (real time clock) +--------------------- + +See :ref:`pyb.RTC <pyb.RTC>` :: + + from pyb import RTC + + rtc = RTC() + rtc.datetime((2017, 8, 23, 1, 12, 48, 0, 0)) # set a specific date and time + rtc.datetime() # get date and time + PWM (pulse width modulation) ---------------------------- @@ -167,3 +193,25 @@ See :ref:`pyb.I2C <pyb.I2C>`. :: i2c.recv(5, 0x42) # receive 5 bytes from slave i2c.mem_read(2, 0x42, 0x10) # read 2 bytes from slave 0x42, slave memory 0x10 i2c.mem_write('xy', 0x42, 0x10) # write 2 bytes to slave 0x42, slave memory 0x10 + +CAN bus (controller area network) +--------------------------------- + +See :ref:`pyb.CAN <pyb.CAN>`. :: + + from pyb import CAN + + can = CAN(1, CAN.LOOPBACK) + can.setfilter(0, CAN.LIST16, 0, (123, 124, 125, 126)) + can.send('message!', 123) # send a message with id 123 + can.recv(0) # receive message on FIFO 0 + +Internal accelerometer +---------------------- + +See :ref:`pyb.Accel <pyb.Accel>`. :: + + from pyb import Accel + + accel = Accel() + print(accel.x(), accel.y(), accel.z(), accel.tilt()) diff --git a/docs/pyboard/tutorial/leds.rst b/docs/pyboard/tutorial/leds.rst index 763eedf01..6b05f5db0 100644 --- a/docs/pyboard/tutorial/leds.rst +++ b/docs/pyboard/tutorial/leds.rst @@ -60,10 +60,10 @@ One problem you might find is that if you stop the script and then start it agai for l in leds: l.off() -The Fourth Special LED ----------------------- +The Special LEDs +---------------- -The blue LED is special. As well as turning it on and off, you can control the intensity using the intensity() method. This takes a number between 0 and 255 that determines how bright it is. The following script makes the blue LED gradually brighter then turns it off again. :: +The yellow and blue LEDs are special. As well as turning them on and off, you can control their intensity using the intensity() method. This takes a number between 0 and 255 that determines how bright it is. The following script makes the blue LED gradually brighter then turns it off again. :: led = pyb.LED(4) intensity = 0 @@ -72,4 +72,4 @@ The blue LED is special. As well as turning it on and off, you can control the i led.intensity(intensity) pyb.delay(20) -You can call intensity() on the other LEDs but they can only be off or on. 0 sets them off and any other number up to 255 turns them on. +You can call intensity() on LEDs 1 and 2 but they can only be off or on. 0 sets them off and any other number up to 255 turns them on. diff --git a/docs/reference/isr_rules.rst b/docs/reference/isr_rules.rst index 5009f30f7..2db261c09 100644 --- a/docs/reference/isr_rules.rst +++ b/docs/reference/isr_rules.rst @@ -80,7 +80,7 @@ example causes two LED's to flash at different rates. self.led.toggle() red = Foo(pyb.Timer(4, freq=1), pyb.LED(1)) - greeen = Foo(pyb.Timer(2, freq=0.8), pyb.LED(2)) + green = Foo(pyb.Timer(2, freq=0.8), pyb.LED(2)) In this example the ``red`` instance associates timer 4 with LED 1: when a timer 4 interrupt occurs ``red.cb()`` is called causing LED 1 to change state. The ``green`` instance operates similarly: a timer 2 interrupt |