From add933feaf188073de99cf54e4d251c48034472c Mon Sep 17 00:00:00 2001 From: Damien George Date: Thu, 5 Oct 2017 15:27:50 +1100 Subject: docs/library/network: Clarify usage of "bssid" arg in connect() method. --- docs/library/network.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/library/network.rst b/docs/library/network.rst index def6bee74..258b2a20c 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() @@ -333,9 +332,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() -- cgit v1.2.3 From d236d0c415bc34c96e7155ab116258a026b2cda6 Mon Sep 17 00:00:00 2001 From: Mike Causer Date: Fri, 6 Oct 2017 01:01:05 +1100 Subject: docs/pyboard/quickref: Add info for Switch, RTC, CAN, Accel classes. --- docs/pyboard/quickref.rst | 54 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 3 deletions(-) (limited to 'docs') 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 ` 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 `. :: 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 `. :: + + 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 `. :: tim.freq(0.5) # 0.5 Hz tim.callback(lambda t: pyb.LED(1).toggle()) +RTC (real time clock) +--------------------- + +See :ref:`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 `. :: 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 `. :: + + 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 `. :: + + from pyb import Accel + + accel = Accel() + print(accel.x(), accel.y(), accel.z(), accel.tilt()) -- cgit v1.2.3 From dc92f1c4ee0924cff0b33b5061622f0621e71eac Mon Sep 17 00:00:00 2001 From: Mike Causer Date: Fri, 6 Oct 2017 01:36:48 +1100 Subject: docs/pyboard/tutorial: Update now that yellow LED also supports PWM. --- docs/pyboard/tutorial/leds.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') 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. -- cgit v1.2.3 From f599a380591df2a7bb466eae6a4144634409821b Mon Sep 17 00:00:00 2001 From: Mike Causer Date: Fri, 6 Oct 2017 01:48:43 +1100 Subject: docs/esp8266/quickref: Add quickref info for RTC class. --- docs/esp8266/quickref.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') 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 ` 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 ` :: + + 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 --------------- -- cgit v1.2.3 From b1457db002a7205727f49c48f56ed270e2568d6a Mon Sep 17 00:00:00 2001 From: Mike Causer Date: Wed, 11 Oct 2017 01:24:44 +1100 Subject: docs/library: Add missing cross-ref links for classes in pyb module. --- docs/library/pyb.Accel.rst | 1 + docs/library/pyb.CAN.rst | 1 + docs/library/pyb.LCD.rst | 1 + docs/library/pyb.Switch.rst | 1 + docs/library/pyb.USB_HID.rst | 1 + docs/library/pyb.USB_VCP.rst | 1 + 6 files changed, 6 insertions(+) (limited to 'docs') 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 ====================================== -- cgit v1.2.3 From 65ba481cb0e067a97f8a999e2522b0656ca3b7fe Mon Sep 17 00:00:00 2001 From: Damien George Date: Mon, 16 Oct 2017 13:16:00 +1100 Subject: stm32/modnwwiznet5k: Implement WIZNET5K.isconnected() method. --- docs/library/network.rst | 5 +++++ ports/stm32/modnwwiznet5k.c | 7 +++++++ 2 files changed, 12 insertions(+) (limited to 'docs') diff --git a/docs/library/network.rst b/docs/library/network.rst index 258b2a20c..acb578a7c 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -268,6 +268,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. diff --git a/ports/stm32/modnwwiznet5k.c b/ports/stm32/modnwwiznet5k.c index 78249816d..a9e5f5aa9 100644 --- a/ports/stm32/modnwwiznet5k.c +++ b/ports/stm32/modnwwiznet5k.c @@ -414,6 +414,12 @@ STATIC mp_obj_t wiznet5k_regs(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(wiznet5k_regs_obj, wiznet5k_regs); +STATIC mp_obj_t wiznet5k_isconnected(mp_obj_t self_in) { + (void)self_in; + return mp_obj_new_bool(wizphy_getphylink() == PHY_LINK_ON); +} +STATIC MP_DEFINE_CONST_FUN_OBJ_1(wiznet5k_isconnected_obj, wiznet5k_isconnected); + /// \method ifconfig([(ip, subnet, gateway, dns)]) /// Get/set IP address, subnet mask, gateway and DNS. STATIC mp_obj_t wiznet5k_ifconfig(size_t n_args, const mp_obj_t *args) { @@ -445,6 +451,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(wiznet5k_ifconfig_obj, 1, 2, wiznet5k STATIC const mp_rom_map_elem_t wiznet5k_locals_dict_table[] = { { MP_ROM_QSTR(MP_QSTR_regs), MP_ROM_PTR(&wiznet5k_regs_obj) }, { MP_ROM_QSTR(MP_QSTR_ifconfig), MP_ROM_PTR(&wiznet5k_ifconfig_obj) }, + { MP_ROM_QSTR(MP_QSTR_isconnected), MP_ROM_PTR(&wiznet5k_isconnected_obj) }, }; STATIC MP_DEFINE_CONST_DICT(wiznet5k_locals_dict, wiznet5k_locals_dict_table); -- cgit v1.2.3 From d90ade5e3e62b28c1f04d18f206509a488d62ec0 Mon Sep 17 00:00:00 2001 From: Damien George Date: Mon, 16 Oct 2017 15:51:56 +1100 Subject: docs/library/network: Update docs to state that W5500 is supported. --- docs/library/network.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/library/network.rst b/docs/library/network.rst index acb578a7c..3b0aa535e 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -224,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:: -- cgit v1.2.3 From 328c1e78be68a386fe6fb5940027aad887c823a4 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Thu, 26 Oct 2017 00:28:45 +0300 Subject: docs/uselect: Document one-shot polling mode. --- docs/library/uselect.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'docs') 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 -- cgit v1.2.3 From d1cd533134cc115dfe15e6c22d60bb7fd7589d88 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Thu, 26 Oct 2017 14:00:16 +0300 Subject: docs/usocket: Elaborate descriptions. Use the "usocket" module name everywhere. Use "MicroPython port" terminology. Suggest to avoid using IPPROTO_* constants in socket() call. --- docs/library/usocket.rst | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index dfdcd68bc..a3e987a07 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 @@ -102,7 +111,7 @@ 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 +121,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_* @@ -281,7 +294,7 @@ Methods Return value: number of bytes written. -.. exception:: socket.error +.. exception:: usocket.error MicroPython does NOT have this exception. -- cgit v1.2.3 From a33fca99a1cc9d2026ee56e81f372c1e695379f5 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Fri, 27 Oct 2017 00:27:27 +0300 Subject: docs/usocket: Document inet_ntop(), inet_pton(). --- docs/library/usocket.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs') diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index a3e987a07..53936505b 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -105,6 +105,22 @@ 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 --------- -- cgit v1.2.3 From b9923262db4600b3618aa143bb4bcc93bf299814 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Wed, 25 Oct 2017 14:18:11 +0200 Subject: docs/library/network: Add dhcp_hostname parameter I have not actually tested this, going by information available in https://forum.micropython.org/viewtopic.php?t=2584 --- docs/library/network.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/library/network.rst b/docs/library/network.rst index 3b0aa535e..99a7c242c 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -422,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 + ============= =========== -- cgit v1.2.3 From 05a2bb888f9cd3dc3e005b8eea4258e20a39cba2 Mon Sep 17 00:00:00 2001 From: Yuval Langer Date: Sun, 29 Oct 2017 22:27:06 +0200 Subject: docs/reference/isr_rules: Minor typo correction. --- docs/reference/isr_rules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') 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 -- cgit v1.2.3 From 6fb093282b9f987618063e1945da98d2e4ed3334 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Mon, 30 Oct 2017 18:03:54 +0200 Subject: docs/ussl: Fix module name refs and use "MicroPython port" term. --- docs/library/ussl.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs') 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. -- cgit v1.2.3 From 4dd523adbbe8852c9e02191d4a67ea6c7aa72aec Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Mon, 30 Oct 2017 19:49:37 +0200 Subject: docs/esp8266/general: Add section on TLS limitations. --- docs/esp8266/general.rst | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'docs') 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 `_ 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. -- cgit v1.2.3 From b81fbf938f1bb9cc798a3933476c80c0d9b83992 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 31 Oct 2017 00:28:28 +0200 Subject: docs/usocket: Document that settimeout() isn't supported by all ports. And describe an alternative of using uselect.poll(). --- docs/library/usocket.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs') diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index 53936505b..fab05b652 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -237,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 -- cgit v1.2.3 From 80e3f07e7f760707f20200b6b6a706308d92158c Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 31 Oct 2017 14:45:26 +0200 Subject: docs/ure: Add "|" (alternative) to the list of supported operators. --- docs/library/ure.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') 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). -- cgit v1.2.3 From fe45d78b1edd6d2202c3544797885cb0b12d4f03 Mon Sep 17 00:00:00 2001 From: Damien George Date: Wed, 1 Nov 2017 11:19:56 +1100 Subject: docs: Bump version to 1.9.3. --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index a8df37315..5352d16e4 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -98,7 +98,7 @@ copyright = '2014-2017, Damien P. George, Paul Sokolovsky, and contributors' # # We don't follow "The short X.Y version" vs "The full version, including alpha/beta/rc tags" # breakdown, so use the same version identifier for both to avoid confusion. -version = release = '1.9.2' +version = release = '1.9.3' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3