.. currentmodule:: network
.. _network.WLANWiPy:

class WLANWiPy -- WiPy specific WiFi control
类WLANWiPy - WiPy特定WiFi控制
============================================

.. note::

    This class is a non-standard WLAN implementation for the WiPy.
    It is available simply as ``network.WLAN`` on the WiPy but is named in the
    documentation below as ``network.WLANWiPy`` to distinguish it from the
    more general :ref:`network.WLAN <network.WLAN>` class.
    这个类是WiPy的非标准WLAN实现。
    它可以简单地称为``network.WLAN`` 在WiPy上却被命名为
    文件如下为``network.WLANWiPy``来区分它和
    更普遍的::ref:`network.WLAN <network.WLAN>`类。

This class provides a driver for the WiFi network processor in the WiPy. Example usage::
这个类为WiPy中的WiFi网络处理器提供一个驱动程序。用法例子::

    import network
    import time
    # setup as a station
    # 设置为工作站
    wlan = network.WLAN(mode=WLAN.STA)
    wlan.connect('your-ssid', auth=(WLAN.WPA2, 'your-key'))
    while not wlan.isconnected():
        time.sleep_ms(50)
    print(wlan.ifconfig())

    # now use socket as usual
    # 现在像往常一样使用套接字
    ...

Constructors
构造函数
------------

.. class:: WLANWiPy(id=0, ...)

   Create a WLAN object, and optionally configure it. See `init()` for params of configuration.
   创建一个WLAN对象，并可选地配置它。参见' init() '获取配置参数。

.. note::

   The ``WLAN`` constructor is special in the sense that if no arguments besides the id are given,
   it will return the already existing ``WLAN`` instance without re-configuring it. This is
   because ``WLAN`` is a system feature of the WiPy. If the already existing instance is not
   initialized it will do the same as the other constructors an will initialize it with default
   values.
   ``WLAN``构造函数是特殊的，如果除了id之外没有参数，
   它将返回已经存在的``WLAN``实例，而不需要重新配置它。这是
   因为``WLAN``是WiPy的一个系统特性。如果已经存在的实例不是
   它将做相同的其他构造函数，an将初始化它的默认值
   值。

Methods
方法
-------

.. method:: WLANWiPy.init(mode, \*, ssid, auth, channel, antenna)

   Set or get the WiFi network processor configuration.
   设置或获取WiFi网络处理器配置。

   Arguments are:
   参数:

     - *mode* can be either ``WLAN.STA`` or ``WLAN.AP``.
     - *mode* 可以是``WLAN.STA`` 或 ``WLAN.AP``。
     - *ssid* is a string with the ssid name. Only needed when mode is ``WLAN.AP``.
     - *ssid* 是一个具有ssid名称的字符串。只有当模式是``WLAN.AP``时才需要。
     - *auth* is a tuple with (sec, key). Security can be ``None``, ``WLAN.WEP``,
       ``WLAN.WPA`` or ``WLAN.WPA2``. The key is a string with the network password.
     - *auth*是一个具有(sec, key)的元组。安全可以是``None``, ``WLAN.WEP``,
       ``WLAN.WPA`` 或 ``WLAN.WPA2``。密钥是一个带有网络密码的字符串。
       If ``sec`` is ``WLAN.WEP`` the key must be a string representing hexadecimal
       values (e.g. 'ABC1DE45BF'). Only needed when mode is ``WLAN.AP``.
       如果``sec`` 是 ``WLAN.WEP``密钥必须是表示十六进制的字符串
       值(e.g. 'ABC1DE45BF')。只有当模式是``WLAN.AP``时才需要。
     - *channel* a number in the range 1-11. Only needed when mode is ``WLAN.AP``.
     - *channel* 一个范围在1-11的数字。只有当模式是``WLAN.AP``时才需要。
     - *antenna* selects between the internal and the external antenna. Can be either
       ``WLAN.INT_ANT`` or ``WLAN.EXT_ANT``.
     - *antenna* 在内部和外部天线之间选择。可以是
       ``WLAN.INT_ANT`` or ``WLAN.EXT_ANT``。

   For example, you can do::
   例如，你可以::

      # create and configure as an access point
      # 创建并配置为访问点
      wlan.init(mode=WLAN.AP, ssid='wipy-wlan', auth=(WLAN.WPA2,'www.wipy.io'), channel=7, antenna=WLAN.INT_ANT)

   or::

      # configure as an station
      # 配置为工作站
      wlan.init(mode=WLAN.STA)

.. method:: WLANWiPy.connect(ssid, \*, auth=None, bssid=None, timeout=None)

   Connect to a WiFi access point using the given SSID, and other security
   parameters.
   使用给定的SSID和其他安全措施连接到WiFi接入点
   参数。

      - *auth* is a tuple with (sec, key). Security can be ``None``, ``WLAN.WEP``,
        ``WLAN.WPA`` or ``WLAN.WPA2``. The key is a string with the network password.
      - *auth*是具有(sec, key)的元组。安全可以是``None``, ``WLAN.WEP``,
        ``WLAN.WPA`` or ``WLAN.WPA2``。密钥是一个带有网络密码的字符串。
        If ``sec`` is ``WLAN.WEP`` the key must be a string representing hexadecimal
        values (e.g. 'ABC1DE45BF').
        如果``sec`` 是 ``WLAN.WEP``密钥必须是表示十六进制的字符串values (e.g. 'ABC1DE45BF')
      - *bssid* is the MAC address of the AP to connect to. Useful when there are several
        APs with the same ssid.
      - *bssid*是AP要连接的MAC地址。当有几个时很有用
        具有相同ssid的APs。
      - *timeout* is the maximum time in milliseconds to wait for the connection to succeed.
      - *timeout* 等待连接成功的最大时间(以毫秒为单位)。

.. method:: WLANWiPy.scan()

   Performs a network scan and returns a list of named tuples with (ssid, bssid, sec, channel, rssi).
   Note that channel is always ``None`` since this info is not provided by the WiPy.
   执行网络扫描并通过(ssid、bssid、sec、channel、rssi)返回一个命名元组列表。
   注意通道总是``None``因为WiPy不提供此信息。

.. method:: WLANWiPy.disconnect()

   Disconnect from the WiFi access point.
   断开WiFi接入点。

.. method:: WLANWiPy.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, ``False`` otherwise.
   在STA模式下，如果连接到WiFi接入点并且有一个有效的IP地址，返回``True``。
   在AP模式下，当站点连接时返回``True``，否则返回``True``。

.. method:: WLANWiPy.ifconfig(if_id=0, config=['dhcp' or configtuple])

   With no parameters given returns a 4-tuple of *(ip, subnet_mask, gateway, DNS_server)*.
   返回一个4元组*(ip, subnet_mask, gateway, DNS_server)*。

   if ``'dhcp'`` is passed as a parameter then the DHCP client is enabled and the IP params
   are negotiated with the AP.
   如果``'dhcp'``是作为参数传递的，那么dhcp客户端是启用的，IP参数
   都是与美联社协商的

   If the 4-tuple config is given then a static IP is configured. For instance::
   如果给定了4元组配置，则配置一个静态IP。例如::

      wlan.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))

.. method:: WLANWiPy.mode([mode])

   Get or set the WLAN mode.
   获取或设置WLAN模式。

.. method:: WLANWiPy.ssid([ssid])

   Get or set the SSID when in AP mode.
   在AP模式下获取或设置SSID。

.. method:: WLANWiPy.auth([auth])

   Get or set the authentication type when in AP mode.
   在AP模式下获取或设置身份验证类型。

.. method:: WLANWiPy.channel([channel])

   Get or set the channel (only applicable in AP mode).
   获取或设置频道(仅适用于AP模式)。

.. method:: WLANWiPy.antenna([antenna])

   Get or set the antenna type (external or internal).
   获取或设置天线类型(外部或内部)。

.. method:: WLANWiPy.mac([mac_addr])

   Get or set a 6-byte long bytes object with the MAC address.
   获取或设置一个具有MAC地址的6字节长的字节对象。

.. method:: WLANWiPy.irq(\*, handler, wake)

    Create a callback to be triggered when a WLAN event occurs during ``machine.SLEEP``
    mode. Events are triggered by socket activity or by WLAN connection/disconnection.
    创建一个回调，当WLAN事件发生时，在``machine.SLEEP``
    模式。事件由套接字活动或WLAN连接/断开触发。

        - *handler* is the function that gets called when the IRQ is triggered.
        - *handler* 是当IRQ被触发时被调用的函数。
        - *wake* must be ``machine.SLEEP``.

    Returns an IRQ object.
    返回一个IRQ对象。

Constants
常量
---------

.. data:: WLANWiPy.STA
.. data:: WLANWiPy.AP

   selects the WLAN mode
   选择WLAN模式

.. data:: WLANWiPy.WEP
.. data:: WLANWiPy.WPA
.. data:: WLANWiPy.WPA2

   selects the network security
   选择网络安全

.. data:: WLANWiPy.INT_ANT
.. data:: WLANWiPy.EXT_ANT

   selects the antenna type
   选择天线类型