From ca16c3821053e5bf2b87aeb10007f73f31dc1eac Mon Sep 17 00:00:00 2001 From: Ville Skyttä Date: Mon, 29 May 2017 10:08:14 +0300 Subject: various: Spelling fixes --- docs/library/btree.rst | 2 +- docs/library/machine.SD.rst | 2 +- docs/library/machine.UART.rst | 2 +- docs/library/uhashlib.rst | 4 ++-- docs/library/utime.rst | 4 ++-- 5 files changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/library') 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.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/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/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. -- cgit v1.2.3 From 3496d9e4bd39452484d8a99e991ef7c0a92d5b51 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Mon, 29 May 2017 20:51:30 +0300 Subject: docs/machine.Pin: Remove out_value() method. This method isn't implemented in any port. It seemed to have originated in cc3200 port, but actually never was implemented there either. In general case, it's impossible to implement this method (for example, for a perfect GPO, which has only output latch without any feedback look into a CPU). --- docs/library/machine.Pin.rst | 6 ------ 1 file changed, 6 deletions(-) (limited to 'docs/library') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 2efd84688a..e7f3141542 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -146,12 +146,6 @@ 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 -- cgit v1.2.3 From d5b8825d5f5c6110f9cf3bd39848cfe94137d291 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Mon, 29 May 2017 20:56:13 +0300 Subject: docs/machine.Pin: Add on() and off() methods. --- docs/library/machine.Pin.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/library') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index e7f3141542..05ceb4ad33 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -152,6 +152,14 @@ Methods 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. -- cgit v1.2.3 From 92206a78aeddf81eca08fb25589231e5a62df69c Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 3 Jun 2017 13:34:28 +0300 Subject: docs/network: Move confusingly-named cc3200 Server class to its reference. cc3200 port has network.Server class to control behavior of builtin Telnet/FTP server of that port. --- docs/library/network.rst | 46 ---------------------------------------------- docs/wipy/general.rst | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 46 deletions(-) (limited to 'docs/library') diff --git a/docs/library/network.rst b/docs/library/network.rst index 251e68c76e..75640250f7 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -29,52 +29,6 @@ For example:: data = s.recv(1000) s.close() -.. only:: port_wipy - - .. _network.Server: - - 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. - - 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) - - Constructors - ------------ - - .. class:: network.Server(id, ...) - - Create a server instance, see ``init`` for parameters of initialization. - - Methods - ------- - - .. 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. - .. only:: port_pyboard class CC3K diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index 8b9b91c534..ca6f77ab05 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -323,3 +323,40 @@ Unrelated function in machine module 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. + -- cgit v1.2.3 From 1ce44f30467e4882580ca8545f15ba7d882cb428 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 3 Jun 2017 13:51:13 +0300 Subject: docs/uos: Deconditionalize, remove minor port-specific details. For a couple of ports, there was information which directory is set as current after boot. This information doesn't belong to "uos" module, and is moved to boards' references (which actually already contained information on which directory is chosen for boot, even if without explicit mentioning that it becomes current directory, which is now done). --- docs/library/uos.rst | 21 +-------------------- docs/pyboard/general.rst | 4 +++- docs/wipy/general.rst | 2 +- 3 files changed, 5 insertions(+), 22 deletions(-) (limited to 'docs/library') diff --git a/docs/library/uos.rst b/docs/library/uos.rst index d1f83d2cc3..82ed5dbc93 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 --------- diff --git a/docs/pyboard/general.rst b/docs/pyboard/general.rst index 48e0146442..1d040f6ccc 100644 --- a/docs/pyboard/general.rst +++ b/docs/pyboard/general.rst @@ -10,7 +10,9 @@ is inserted into the slot, it is available as ``/sd``. When the pyboard boots up, it needs to choose a filesystem to boot from. If there is no SD card, then it uses the internal filesystem ``/flash`` as the boot -filesystem, otherwise, it uses the SD card ``/sd``. +filesystem, otherwise, it uses the SD card ``/sd``. After the boot, the current +directory is set to one of the directories above. + If needed, you can prevent the use of the SD card by creating an empty file called ``/flash/SKIPSD``. If this file exists when the pyboard boots up then the SD card will be skipped and the pyboard will always boot from the diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index ca6f77ab05..1e396518e0 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: -- cgit v1.2.3 From e91b1cdae38d693fbd34a57341d8c72737f0ec22 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 3 Jun 2017 14:19:53 +0300 Subject: docs/uos: Move cc3200 port legacy VFS mounting functions to its ref doc. This patch also unconditionalizes uos.dupterm(), though exact interface and semantics is yet to be defined. --- docs/library/uos.rst | 26 ++++---------------------- docs/wipy/general.rst | 23 +++++++++++++++++++++++ 2 files changed, 27 insertions(+), 22 deletions(-) (limited to 'docs/library') diff --git a/docs/library/uos.rst b/docs/library/uos.rst index 82ed5dbc93..3d0aa46c70 100644 --- a/docs/library/uos.rst +++ b/docs/library/uos.rst @@ -87,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:: dupterm(stream_object) - .. 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) - - 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/wipy/general.rst b/docs/wipy/general.rst index 1e396518e0..f28edb4e4b 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -360,3 +360,26 @@ Example:: 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. + -- cgit v1.2.3 From f245f5d7cc62ae60c73d51d9962a995ff3e579c5 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 3 Jun 2017 14:50:54 +0300 Subject: docs/machine: Sort machine classes in logical order, not alphabetically. The list starts with the simplest functionality - GPIO, proceeds to communication interfaces (UART, SPI, I2C), the to time(r) related things, then everything else. --- docs/library/machine.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/library') 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 -- cgit v1.2.3 From cd64b3082e501f5a54cb15ab3087be91c8f90338 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 9 Apr 2017 13:21:35 +0300 Subject: docs/network: First step to describe standard network class interface. This adds description of implied AbstractNIC base class, which should be "subclasses" and implemented by a particular network device class. This is just an initial step in that direction, the API and description will be elabotated further. --- docs/library/network.rst | 109 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 106 insertions(+), 3 deletions(-) (limited to 'docs/library') diff --git a/docs/library/network.rst b/docs/library/network.rst index 75640250f7..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,6 +35,103 @@ For example:: data = s.recv(1000) s.close() +Common network adapter interface +================================ + +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:: AbstractNIC(id=None, ...) + +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`. + + .. method:: active([is_active]) + + 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). + + .. method:: connect([service_id, key=None, \*, ...]) + + 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: + + * WiFi: `bssid` keyword to connect by BSSID (MAC address) instead + of access point name + + .. 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. + + 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(). + + .. method:: status() + + Return detailed status of the interface, values are dependent + on the network medium/technology. + + .. method:: ifconfig([(ip, subnet, gateway, dns)]) + + 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:: + + nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) + + .. method:: config('param') + config(param=value, ...) + + 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 class CC3K -- cgit v1.2.3