diff options
Diffstat (limited to 'docs/library')
| -rw-r--r-- | docs/library/btree.rst | 2 | ||||
| -rw-r--r-- | docs/library/machine.Pin.rst | 14 | ||||
| -rw-r--r-- | docs/library/machine.SD.rst | 2 | ||||
| -rw-r--r-- | docs/library/machine.UART.rst | 2 | ||||
| -rw-r--r-- | docs/library/machine.rst | 16 | ||||
| -rw-r--r-- | docs/library/network.rst | 119 | ||||
| -rw-r--r-- | docs/library/uhashlib.rst | 4 | ||||
| -rw-r--r-- | docs/library/uos.rst | 47 | ||||
| -rw-r--r-- | docs/library/utime.rst | 4 |
9 files changed, 116 insertions, 94 deletions
diff --git a/docs/library/btree.rst b/docs/library/btree.rst index aebcbc1604..bd7890586a 100644 --- a/docs/library/btree.rst +++ b/docs/library/btree.rst @@ -69,7 +69,7 @@ Functions Open a database from a random-access `stream` (like an open file). All other parameters are optional and keyword-only, and allow to tweak advanced - paramters of the database operation (most users will not need them): + parameters of the database operation (most users will not need them): * `flags` - Currently unused. * `cachesize` - Suggested maximum memory cache size in bytes. For a diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 2efd84688a..05ceb4ad33 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -146,18 +146,20 @@ Methods When setting the value this method returns ``None``. -.. method:: Pin.out_value() - - Return the value stored in the output buffer of a pin, regardless of its mode. - - Not all ports implement this method. - .. method:: Pin.__call__([x]) Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin. It is equivalent to Pin.value([x]). See :meth:`Pin.value` for more details. +.. method:: Pin.on() + + Set pin to "1" output level. + +.. method:: Pin.off() + + Set pin to "0" output level. + .. method:: Pin.mode([mode]) Get or set the pin mode. diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst index 0eb024602f..608e958317 100644 --- a/docs/library/machine.SD.rst +++ b/docs/library/machine.SD.rst @@ -34,7 +34,7 @@ Methods .. method:: SD.init(id=0, pins=('GP10', 'GP11', 'GP15')) - Enable the SD card. In order to initalize the card, give it a 3-tuple: + Enable the SD card. In order to initialize the card, give it a 3-tuple: ``(clk_pin, cmd_pin, dat0_pin)``. .. method:: SD.deinit() diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index f9c8efef78..64ff28e1ab 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -16,7 +16,7 @@ UART objects can be created and initialised using:: uart = UART(1, 9600) # init with given baudrate uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters -Supported paramters differ on a board: +Supported parameters differ on a board: Pyboard: Bits can be 7, 8 or 9. Stop can be 1 or 2. With `parity=None`, only 8 and 9 bits are supported. With parity enabled, only 7 and 8 bits diff --git a/docs/library/machine.rst b/docs/library/machine.rst index c2c6b83fd6..7ea7f565e7 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -145,13 +145,13 @@ Classes .. toctree:: :maxdepth: 1 - machine.I2C.rst machine.Pin.rst machine.Signal.rst - machine.RTC.rst + machine.UART.rst machine.SPI.rst + machine.I2C.rst + machine.RTC.rst machine.Timer.rst - machine.UART.rst machine.WDT.rst .. only:: port_wipy @@ -159,12 +159,12 @@ Classes .. toctree:: :maxdepth: 1 - machine.ADC.rst - machine.I2C.rst machine.Pin.rst - machine.RTC.rst - machine.SD.rst + machine.UART.rst machine.SPI.rst + machine.I2C.rst + machine.RTC.rst machine.Timer.rst - machine.UART.rst machine.WDT.rst + machine.ADC.rst + machine.SD.rst diff --git a/docs/library/network.rst b/docs/library/network.rst index 251e68c76e..27fa0dcb2f 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -14,14 +14,20 @@ module. For example:: - # configure a specific network interface + # connect/ show IP config a specific network interface # see below for examples of specific drivers import network + import utime nic = network.Driver(...) + if not nic.isconnected(): + nic.connect() + print("Waiting for connection...") + while not nic.isconnected(): + utime.sleep(1) print(nic.ifconfig()) - # now use socket as usual - import socket + # now use usocket as usual + import usocket as socket addr = socket.getaddrinfo('micropython.org', 80)[0][-1] s = socket.socket() s.connect(addr) @@ -29,51 +35,102 @@ For example:: data = s.recv(1000) s.close() -.. only:: port_wipy +Common network adapter interface +================================ - .. _network.Server: +This section describes an (implied) abstract base class for all network +interface classes implemented by different ports of MicroPython for +different hardware. This means that MicroPython does not actually +provide `AbstractNIC` class, but any actual NIC class, as described +in the following sections, implements methods as described here. - class Server - ============ +.. class:: AbstractNIC(id=None, ...) - 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. +Instantiate a network interface object. Parameters are network interface +dependent. If there are more than one interface of the same type, the first +parameter should be `id`. - Example:: + .. method:: active([is_active]) - import network - server = network.Server() - server.deinit() # disable the server - # enable the server again with new settings - server.init(login=('user', 'password'), timeout=600) + Activate ("up") or deactivate ("down") the network interface, if + a boolean argument is passed. Otherwise, query current state if + no argument is provided. Most other methods require an active + interface (behavior of calling them on inactive interface is + undefined). - Constructors - ------------ + .. method:: connect([service_id, key=None, \*, ...]) - .. class:: network.Server(id, ...) + Connect the interface to a network. This method is optional, and + available only for interfaces which are not "always connected". + If no parameters are given, connect to the default (or the only) + service. If a single parameter is given, it is the primary identifier + of a service to connect to. It may be accompanied by a key + (password) required to access said service. There can be further + arbitrary keyword-only parameters, depending on the networking medium + type and/or particular device. Parameters can be used to: a) + specify alternative service identifer types; b) provide additional + connection parameters. For various medium types, there are different + sets of predefined/recommended parameters, among them: - Create a server instance, see ``init`` for parameters of initialization. + * WiFi: `bssid` keyword to connect by BSSID (MAC address) instead + of access point name - Methods - ------- + .. method:: disconnect() + + Disconnect from network. + + .. method:: isconnected() + + Returns ``True`` if connected to network, otherwise returns ``False``. + + .. method:: scan(\*, ...) + + Scan for the available network services/connections. Returns a + list of tuples with discovered service parameters. For various + network media, there are different variants of predefined/ + recommended tuple formats, among them: + + * WiFi: (ssid, bssid, channel, RSSI, authmode, hidden). There + may be further fields, specific to a particular device. - .. method:: server.init(\*, login=('micro', 'python'), timeout=300) + The function may accept additional keyword arguments to filter scan + results (e.g. scan for a particular service, on a particular channel, + for services of a particular set, etc.), and to affect scan + duration and other parameters. Where possible, parameter names + should match those in connect(). - Init (and effectively start the server). Optionally a new ``user``, ``password`` - and ``timeout`` (in seconds) can be passed. + .. method:: status() - .. method:: server.deinit() + Return detailed status of the interface, values are dependent + on the network medium/technology. - Stop the server + .. method:: ifconfig([(ip, subnet, gateway, dns)]) - .. method:: server.timeout([timeout_in_seconds]) + Get/set IP-level network interface parameters: IP address, subnet mask, + gateway and DNS server. When called with no arguments, this method returns + a 4-tuple with the above information. To set the above values, pass a + 4-tuple with the required information. For example:: - Get or set the server timeout. + nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) - .. method:: server.isrunning() + .. method:: config('param') + config(param=value, ...) - Returns ``True`` if the server is running, ``False`` otherwise. + Get or set general network interface parameters. These methods allow to work + with additional parameters beyond standard IP configuration (as dealt with by + ``ifconfig()``). These include network-specific and hardware-specific + parameters and status values. For setting parameters, the keyword argument + syntax should be used, and multiple parameters can be set at once. For + querying, a parameter name should be quoted as a string, and only one + parameter can be queried at a time:: + + # Set WiFi access point name (formally known as ESSID) and WiFi channel + ap.config(essid='My AP', channel=11) + # Query params one by one + print(ap.config('essid')) + print(ap.config('channel')) + # Extended status information also available this way + print(sta.config('rssi')) .. only:: port_pyboard diff --git a/docs/library/uhashlib.rst b/docs/library/uhashlib.rst index cd0216dae9..6b9a764ba8 100644 --- a/docs/library/uhashlib.rst +++ b/docs/library/uhashlib.rst @@ -15,11 +15,11 @@ be implemented: * SHA1 - A previous generation algorithm. Not recommended for new usages, but SHA1 is a part of number of Internet standards and existing - applications, so boards targetting network connectivity and + applications, so boards targeting network connectivity and interoperatiability will try to provide this. * MD5 - A legacy algorithm, not considered cryptographically secure. Only - selected boards, targetting interoperatibility with legacy applications, + selected boards, targeting interoperatibility with legacy applications, will offer this. Constructors diff --git a/docs/library/uos.rst b/docs/library/uos.rst index d1f83d2cc3..3d0aa46c70 100644 --- a/docs/library/uos.rst +++ b/docs/library/uos.rst @@ -4,28 +4,9 @@ .. module:: uos :synopsis: basic "operating system" services -The ``os`` module contains functions for filesystem access and ``urandom`` +The ``uos`` module contains functions for filesystem access and ``urandom`` function. -Port specifics --------------- - -The filesystem has ``/`` as the root directory and the -available physical drives are accessible from here. They are currently: - - ``/flash`` -- the internal flash filesystem - - ``/sd`` -- the SD card (if it exists) - -.. only:: port_pyboard - - On boot up, the current directory is ``/flash`` if no SD card is inserted, - otherwise it is ``/sd``. - -.. only:: port_wipy - - On boot up, the current directory is ``/flash``. - Functions --------- @@ -106,26 +87,8 @@ Functions Return a bytes object with n random bytes. Whenever possible, it is generated by the hardware random number generator. -.. only:: port_wipy - - .. 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. - - .. function:: dupterm(stream_object) +.. function:: dupterm(stream_object) - Duplicate the terminal (the REPL) on the passed stream-like object. - The given object must at least implement the ``.read()`` and ``.write()`` methods. + Duplicate or switch MicroPython terminal (the REPL) on the passed stream-like + object. The given object must implement the `.readinto()` and `.write()` + methods. If ``None`` is passed, previously set redirection is cancelled. diff --git a/docs/library/utime.rst b/docs/library/utime.rst index 871f6c678d..f3a067cdef 100644 --- a/docs/library/utime.rst +++ b/docs/library/utime.rst @@ -146,8 +146,8 @@ Functions too distant inbetween, see below). The function returns **signed** value in the range [``-TICKS_PERIOD/2`` .. ``TICKS_PERIOD/2-1``] (that's a typical range definition for two's-complement signed binary integers). If the result is negative, it means that - ``ticks1`` occured earlier in time than ``ticks2``. Otherwise, it means that - ``ticks1`` occured after ``ticks2``. This holds ``only`` if ``ticks1`` and ``ticks2`` + ``ticks1`` occurred earlier in time than ``ticks2``. Otherwise, it means that + ``ticks1`` occurred after ``ticks2``. This holds ``only`` if ``ticks1`` and ``ticks2`` are apart from each other for no more than ``TICKS_PERIOD/2-1`` ticks. If that does not hold, incorrect result will be returned. Specifically, if two tick values are apart for ``TICKS_PERIOD/2-1`` ticks, that value will be returned by the function. |