From 34d63debd5c339a37009b961b9b51defcdf540ae Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Mon, 25 Jan 2021 08:21:55 -0500 Subject: [PATCH] Remove obsolete esp.rst, network.rst --- docs/library/esp.rst | 85 ------------ docs/library/network.rst | 278 --------------------------------------- 2 files changed, 363 deletions(-) delete mode 100644 docs/library/esp.rst delete mode 100644 docs/library/network.rst diff --git a/docs/library/esp.rst b/docs/library/esp.rst deleted file mode 100644 index 125aaa890f..0000000000 --- a/docs/library/esp.rst +++ /dev/null @@ -1,85 +0,0 @@ -:mod:`esp` --- functions related to the ESP8266 -=============================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: esp - :synopsis: functions related to the ESP8266 - -The ``esp`` module contains specific functions related to the ESP8266 module. - - -Functions ---------- - -.. function:: sleep_type([sleep_type]) - - Get or set the sleep type. - - If the *sleep_type* parameter is provided, sets the sleep type to its - value. If the function is called without parameters, returns the current - sleep type. - - The possible sleep types are defined as constants: - - * ``SLEEP_NONE`` -- all functions enabled, - * ``SLEEP_MODEM`` -- modem sleep, shuts down the WiFi Modem circuit. - * ``SLEEP_LIGHT`` -- light sleep, shuts down the WiFi Modem circuit - and suspends the processor periodically. - - The system enters the set sleep mode automatically when possible. - -.. function:: deepsleep(time=0) - - Enter deep sleep. - - The whole module powers down, except for the RTC clock circuit, which can - be used to restart the module after the specified time if the pin 16 is - connected to the reset pin. Otherwise the module will sleep until manually - reset. - -.. function:: flash_id() - - Read the device ID of the flash memory. - -.. function:: flash_read(byte_offset, length_or_buffer) - -.. function:: flash_write(byte_offset, bytes) - -.. function:: flash_erase(sector_no) - -.. function:: set_native_code_location(start, length) - - Set the location that native code will be placed for execution after it is - compiled. Native code is emitted when the ``@micropython.native``, - ``@micropython.viper`` and ``@micropython.asm_xtensa`` decorators are applied - to a function. The ESP8266 must execute code from either iRAM or the lower - 1MByte of flash (which is memory mapped), and this function controls the - location. - - If *start* and *length* are both ``None`` then the native code location is - set to the unused portion of memory at the end of the iRAM1 region. The - size of this unused portion depends on the firmware and is typically quite - small (around 500 bytes), and is enough to store a few very small - functions. The advantage of using this iRAM1 region is that it does not - get worn out by writing to it. - - If neither *start* nor *length* are ``None`` then they should be integers. - *start* should specify the byte offset from the beginning of the flash at - which native code should be stored. *length* specifies how many bytes of - flash from *start* can be used to store native code. *start* and *length* - should be multiples of the sector size (being 4096 bytes). The flash will - be automatically erased before writing to it so be sure to use a region of - flash that is not otherwise used, for example by the firmware or the - filesystem. - - When using the flash to store native code *start+length* must be less - than or equal to 1MByte. Note that the flash can be worn out if repeated - erasures (and writes) are made so use this feature sparingly. - In particular, native code needs to be recompiled and rewritten to flash - on each boot (including wake from deepsleep). - - In both cases above, using iRAM1 or flash, if there is no more room left - in the specified region then the use of a native decorator on a function - will lead to `MemoryError` exception being raised during compilation of - that function. diff --git a/docs/library/network.rst b/docs/library/network.rst deleted file mode 100644 index 3bd41150d5..0000000000 --- a/docs/library/network.rst +++ /dev/null @@ -1,278 +0,0 @@ -**************************************** -:mod:`network` --- network configuration -**************************************** - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: network - :noindex: - :synopsis: network configuration - -This module provides network drivers and routing configuration. To use this -module, a MicroPython variant/build with network capabilities must be installed. -Network drivers for specific hardware are available within this module and are -used to configure hardware network interface(s). Network services provided -by configured interfaces are then available for use via the :mod:`usocket` -module. - -For example:: - - # 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 usocket as usual - import usocket as socket - addr = socket.getaddrinfo('micropython.org', 80)[0][-1] - s = socket.socket() - s.connect(addr) - s.send(b'GET / HTTP/1.1\r\nHost: micropython.org\r\n\r\n') - 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 ``MicroPython ports `` -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 identifier 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 to a specific BSSID (MAC address) - - .. 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')) - -.. _network.WLAN: - -Functions -========= - -.. function:: phy_mode([mode]) - - Get or set the PHY mode. - - If the *mode* parameter is provided, sets the mode to its value. If - the function is called without parameters, returns the current mode. - - The possible modes are defined as constants: - * ``MODE_11B`` -- IEEE 802.11b, - * ``MODE_11G`` -- IEEE 802.11g, - * ``MODE_11N`` -- IEEE 802.11n. - -class WLAN -========== - -This class provides a driver for WiFi network processor in the ESP8266. Example usage:: - - import network - # enable station interface and connect to WiFi access point - nic = network.WLAN(network.STA_IF) - nic.active(True) - nic.connect('your-ssid', 'your-password') - # now use sockets as usual - -Constructors ------------- -.. class:: WLAN(interface_id) - -Create a WLAN network interface object. Supported interfaces are -``network.STA_IF`` (station aka client, connects to upstream WiFi access -points) and ``network.AP_IF`` (access point, allows other WiFi clients to -connect). Availability of the methods below depends on interface type. -For example, only STA interface may `connect()` to an access point. - -Methods -------- - -.. method:: wlan.active([is_active]) - - Activate ("up") or deactivate ("down") network interface, if boolean - argument is passed. Otherwise, query current state if no argument is - provided. Most other methods require active interface. - -.. 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() - - Disconnect from the currently connected wireless network. - -.. method:: wlan.scan() - - Scan for the available wireless networks. - - Scanning is only possible on STA interface. Returns list of tuples with - the information about WiFi access points: - - (ssid, bssid, channel, RSSI, authmode, hidden) - - *bssid* is hardware address of an access point, in binary form, returned as - bytes object. You can use `binascii.hexlify()` to convert it to ASCII form. - - There are five values for authmode: - - * 0 -- open - * 1 -- WEP - * 2 -- WPA-PSK - * 3 -- WPA2-PSK - * 4 -- WPA/WPA2-PSK - - and two for hidden: - - * 0 -- visible - * 1 -- hidden - -.. method:: wlan.status() - - Return the current status of the wireless connection. - - The possible statuses are defined as constants: - - * ``STAT_IDLE`` -- no connection and no activity, - * ``STAT_CONNECTING`` -- connecting in progress, - * ``STAT_WRONG_PASSWORD`` -- failed due to incorrect password, - * ``STAT_NO_AP_FOUND`` -- failed because no access point replied, - * ``STAT_CONNECT_FAIL`` -- failed due to other problems, - * ``STAT_GOT_IP`` -- connection successful. - -.. method:: wlan.isconnected() - - In case of STA mode, returns ``True`` if connected to a WiFi access - point and has a valid IP address. In AP mode returns ``True`` when a - station is connected. Returns ``False`` otherwise. - -.. method:: wlan.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:: wlan.config('param') - wlan.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 - `wlan.ifconfig()`). These include network-specific and hardware-specific - parameters. For setting parameters, keyword argument syntax should be used, - multiple parameters can be set at once. For querying, parameters name should - be quoted as a string, and only one parameter can be queries at 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')) - - 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) - dhcp_hostname The DHCP hostname to use - ============= ===========