Remove obsolete esp.rst, network.rst
This commit is contained in:
Dan Halbert
parent
69869e1439
commit
34d63debd5
|
|
@ -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.
|
|
||||||
|
|
@ -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 <MicroPython port>``
|
|
||||||
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
|
|
||||||
============= ===========
|
|
||||||
Loading…
Reference in New Issue