diff --git a/content/firmwareapi/micropython/ussl.md b/content/firmwareapi/micropython/ussl.md index 80347f0..c8ed941 100644 --- a/content/firmwareapi/micropython/ussl.md +++ b/content/firmwareapi/micropython/ussl.md @@ -10,7 +10,7 @@ This module provides access to Transport Layer Security (often known as "Secure ## Methods -#### ssl.wrap\_socket(sock, keyfile=None, certfile=None, server\_side=False, cert\_reqs=CERT\_NONE, ssl\_version=0, ca\_certs=None, server\_hostname=None, timeout=10sec) +### ssl.wrap_socket(sock, [keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version=0, ca_certs=None, server_hostname=None, saved_session=None, timeout=10sec]) Takes an instance `sock` of `socket.socket`, and returns an instance of `ssl.SSLSocket`, a subtype of `socket.socket`, which wraps the underlying socket in an SSL context. Example: @@ -40,6 +40,23 @@ SSL sockets inherit all methods and from the standard sockets, see the `usocket` `timeout` : specify a Timeout in Seconds for the SSL handshake operation between client and server, default is 10 seconds +#### ssl.save\_session(ssl_sock) + +Takes an instance `ssl_sock` of `ssl.SSLSocket`, and returns an instance of `ssl.SSLSession`. Saved session can be resumed later, thereby reducing mobile data and time required. Example: + +```python +import socket +import ssl +s = socket.socket() +ss = ssl.wrap_socket(s) +ss.connect(socket.getaddrinfo('www.google.com', 443)[0][-1]) +ses = ssl.save_session(ss) +ss.close() +ss = ssl.wrap_socket(s, saved_session=ses) +ss.connect(socket.getaddrinfo('www.google.com', 443)[0][-1]) +``` + + ## Exceptions * `ssl.SSLError` diff --git a/content/firmwareapi/pycom/network/bluetooth/_index.md b/content/firmwareapi/pycom/network/bluetooth/_index.md index 166cbc5..fbeadc2 100644 --- a/content/firmwareapi/pycom/network/bluetooth/_index.md +++ b/content/firmwareapi/pycom/network/bluetooth/_index.md @@ -60,35 +60,35 @@ bluetooth = Bluetooth() ## Methods -#### bluetooth.init(id=0, mode=Bluetooth.BLE, antenna=None, modem\_sleep=True, pin=None, privacy=True, secure\_connections=True, mtu=200) +### bluetooth.init(id=0, mode=Bluetooth.BLE, antenna=None, modem_sleep=True, pin=None, privacy=True, secure_connections=True, mtu=200) -* `id` Only one Bluetooth peripheral available so must always be 0. -* `mode` currently the only supported mode is `Bluetooth.BLE`. -* `antenna` selects between the internal and the external antenna. Can be either `Bluetooth.INT_ANT`, `Bluetooth.EXT_ANT`. -* `modem_sleep` Enables or Disables BLE modem sleep, Disable modem sleep as a workaround when having Crashes due to flash cache being disabled, as this prevents BLE task saving data in external RAM while accesing external flash for R/W. -* `pin` a one to six digit number (`0`-`9`) to connect to the GATT Sever. Setting any valid pin, GATT Server security features are activated. -* `privacy` Enables or Disables local privacy settings so address will be random or public. + +* `id` Only one Bluetooth peripheral available so must always be 0 * `id` Only one Bluetooth peripheral available so must always be 0. +* `mode` currently the only supported mode is `Bluetooth.BLE` * `mode` currently the only supported mode is `Bluetooth.BLE`. +* `modem_sleep` Enables or Disables BLE modem sleep, Disable modem sleep as a workaround when having Crashes due to flash cache being disabled, as this prevents BLE task saving data in external RAM while accesing external flash for R/W * `antenna` selects between the internal and the external antenna. Can be either `Bluetooth.INT_ANT`, `Bluetooth.EXT_ANT`. +* `antenna` selects between the internal and the external antenna. Can be either `Bluetooth.INT_ANT`, `Bluetooth.EXT_ANT` * `modem_sleep` Enables or Disables BLE modem sleep, Disable modem sleep as a workaround when having Crashes due to flash cache being disabled, as this prevents BLE task saving data in external RAM while accesing external flash for R/W. +* `secure` enables or disables the GATT Server security features * `pin` a one to six digit number (`0`-`9`) to connect to the GATT Sever. Setting any valid pin, GATT Server security features are activated. +* `pin` a six digit number to connect to the GATT Sever * `privacy` Enables or Disables local privacy settings so address will be random or public. * `secure_connections` Enables or Disables Secure Connections and MITM Protection. * `mtu` Maximum Transmission Unit (MTU) is the maximum length of an ATT packet. Value must be between `23` and `200`. -With our development boards it defaults to using the internal antenna, but in the case of an OEM module, the antenna pin (`P12`) is not used, so it's free to be used for other things. + With our development boards it defaults to using the internal antenna, but in the case of an OEM module, the antenna pin (`P12`) is not used, so it's free to be used for other things. With our development boards it defaults to using the internal antenna, but in the case of an OEM module, the antenna pin (`P12`) is not used, so it's free to be used for other things. Initialises and enables the Bluetooth radio in BLE mode. -{{% hint style="info" %}} To use an external antenna, set `P12 as output pin.` ```python Pin('P12', mode=Pin.OUT)(True) ``` -{{% /hint %}} -#### bluetooth.deinit() + +### bluetooth.deinit() Disables the Bluetooth radio. -#### bluetooth.start\_scan(timeout) +### bluetooth.start_scan(timeout) Starts performing a scan listening for BLE devices sending advertisements. This function always returns immediately, the scanning will be performed on the background. The return value is `None`. After starting the scan the function `get_adv()` can be used to retrieve the advertisements messages from the FIFO. The internal FIFO has space to cache 16 advertisements. @@ -103,15 +103,15 @@ bluetooth.start_scan(10) # starts scanning and stop after 10 seconds bluetooth.start_scan(-1) # starts scanning indefinitely until bluetooth.stop_scan() is called ``` -#### bluetooth.stop\_scan() +### bluetooth.stop_scan() Stops an ongoing scanning process. Returns `None`. -#### bluetooth.isscanning() +### bluetooth.isscanning() Returns `True` if a Bluetooth scan is in progress. `False` otherwise. -#### bluetooth.get\_adv() +### bluetooth.get_adv() Gets an named tuple with the advertisement data received during the scanning. The tuple has the following structure: `(mac, addr_type, adv_type, rssi, data)` @@ -133,11 +133,11 @@ adv = bluetooth.get_adv() # ubinascii.hexlify(adv.mac) # convert hexadecimal to ascii ``` -#### bluetooth.get\_advertisements() +### bluetooth.get_advertisements() Same as the `get_adv()` method, but this one returns a list with all the advertisements received. -#### bluetooth.resolve\_adv\_data(data, data\_type) +### bluetooth.resolve_adv_data(data, data_type) Parses the advertisement data and returns the requested `data_type` if present. If the data type is not present, the function returns `None`. @@ -167,11 +167,11 @@ while bluetooth.isscanning(): print(ubinascii.hexlify(mfg_data)) ``` -#### bluetooth.set\_pin() +### bluetooth.set_pin() Configures a new PIN to be used by the device. The PIN is a 1-6 digit length decimal number, if less than 6 digits are given the missing leading digits are considered as 0. E.g. 1234 becomes 001234. When a new PIN is configured, the information of all previously bonded device is removed and the current connection is terminated. To restart advertisement the advertise() must be called after PIN is changed. -#### bluetooth.connect(mac\_addr, timeout=None) +### bluetooth.connect(mac_addr, [timeout=None]) * `mac_addr` is the address of the remote device to connect * `timeout` specifies the amount of time in milliseconds to wait for the connection process to finish. If not given then no timeout is applied The function blocks until the connection succeeds or fails (raises OSError) or the given `timeout` expires (raises `Bluetooth.timeout TimeoutError`). If the connections succeeds it returns a object of type `GATTCConnection`. @@ -180,7 +180,7 @@ Configures a new PIN to be used by the device. The PIN is a 1-6 digit length dec bluetooth.connect('112233eeddff') # mac address is accepted as a string ``` -#### bluetooth.callback(trigger=None, handler=None, arg=None) +### bluetooth.callback([trigger=None, handler=None, arg=None]) Creates a callback that will be executed when any of the triggers occurs. The arguments are: @@ -190,7 +190,7 @@ Creates a callback that will be executed when any of the triggers occurs. The ar An example of how this may be used can be seen in the [`bluetooth.events()`](./#bluetooth-events) method. -#### bluetooth.events() +### bluetooth.events() Returns a value with bit flags identifying the events that have occurred since the last call. Calling this function clears the events. @@ -214,7 +214,7 @@ bluetooth.callback(trigger=Bluetooth.CLIENT_CONNECTED | Bluetooth.CLIENT_DISCONN bluetooth.advertise(True) ``` -#### bluetooth.set\_advertisement(\* , name=None, manufacturer\_data=None, service\_data=None, service\_uuid=None) +### bluetooth.set_advertisement([name=None, manufacturer_data=None, service_data=None, service_uuid=None]) Configure the data to be sent while advertising. If left with the default of `None` the data won't be part of the advertisement message. @@ -231,7 +231,7 @@ Example: bluetooth.set_advertisement(name="advert", manufacturer_data="lopy_v1") ``` -#### bluetooth.set\_advertisement\_params(\* , adv\_int\_min=0x20, adv\_int\_max=0x40, adv\_type=Bluetooth.ADV\_TYPE\_IND, own\_addr\_type=Bluetooth.BLE\_ADDR\_TYPE\_PUBLIC, channel\_map=Bluetooth.ADV\_CHNL\_ALL, adv\_filter\_policy=Bluetooth.ADV\_FILTER\_ALLOW\_SCAN\_ANY\_CON\_ANY) +### bluetooth.set_advertisement_params(adv_int_min=0x20, adv_int_max=0x40, adv_type=Bluetooth.ADV_TYPE_IND, own_addr_type=Bluetooth.BLE_ADDR_TYPE_PUBLIC, channel_map=Bluetooth.ADV_CHNL_ALL, adv_filter_policy=Bluetooth.ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY) Configure the parameters used when advertising. @@ -244,11 +244,11 @@ The arguments are: * `channel_map` is the advertising channel map. * `adv_filter_policy` is the advertising filter policy. -#### bluetooth.advertise(\[Enable\]) +### bluetooth.advertise([Enable]) Start or stop sending advertisements. The `set_advertisement()` method must have been called prior to this one. -#### bluetooth.service(uuid, \* , isprimary=True, nbr\_chars=1, start=True) +#### bluetooth.service(uuid, [isprimary=True, nbr_chars=1, start=True]) Create a new service on the internal GATT server. Returns a object of type `BluetoothServerService`. @@ -263,11 +263,11 @@ The arguments are: bluetooth.service('abc123') ``` -#### bluetooth.disconnect\_client() +### bluetooth.disconnect_client() Closes the BLE connection with the client. -### bluetooth.tx\_power(type, level) +### bluetooth.tx_power(type, level) Gets or sets the TX Power level. If called with only `type` parameter it returns with the current value belonging to the given type. diff --git a/content/firmwareapi/pycom/network/bluetooth/btmesh.md b/content/firmwareapi/pycom/network/bluetooth/btmesh.md new file mode 100644 index 0000000..31eb096 --- /dev/null +++ b/content/firmwareapi/pycom/network/bluetooth/btmesh.md @@ -0,0 +1,116 @@ +--- +title: "Pymesh BLE" +aliases: + - firmwareapi/pycom/network/bluetooth/BLE_Mesh.html + - firmwareapi/pycom/network/bluetooth/BLE_Mesh.md +--- + +The Pymesh BLE library provides support for connecting to a BLE Mesh Network with various Server and Client models. + +For examples, please check the section [Pymesh BLE Examples](/tutorials/all/ble_mesh). + +Pymesh BLE features: + +* Supported Models: + * Configuration Server Model (automatically generated together with primary Element) + * Generic OnOff Server Model + * Generic OnOff Client Model + * Generic Level Server Model + * Generic Level Client Model + * Sensor Server Model + * Sensor Client Model +* Supported OOB authentication types: + * No OOB + * Output OOB +* Supported Node Features: + * GATT Proxy + * Relay +* Only one Element (primary) can be added to the Node. +* Node cannot be configured as Provisioner and a mobile application should be used for Provisioning process + * nRF Mesh (iOS and Android) + * Silicon Labs Bluetoth Mesh (iOS) + * ST BLE Mesh (Android) + * EspBLEMesh (Android) + + +## Methods of BLE_Mesh class + +### BLE_Mesh.init(name="PYCOM-ESP-BLE-MESH", *, auth=0, callback=None) + +Initializes the BLE Mesh module with the pre-configured Elements and Models. + +* `name` is the name which will be used to identify the device during Provisioning +* `auth` is the Out-Of-Band (OOB) method. Currently `BLE_Mesh.OOB_OUTPUT` is supported. Without specifying this argument, `NO_OOB` will be used during provisioning. +* `callback` is the callback to be registered. It must have the following arguments: + * `event` returns current event of provisioning. + * `oob_pass` returns the generated pass in case of `BLE_Mesh.OOB_OUTPUT`. + +### BLE_Mesh.set_node_prov(bearer=BLE_Mesh.PROV_NONE, *) + +Enable provisioning bearers to get the device ready for provisioning. If OOB is enabled, the callback is used to inform the user about OOB information. + +* `bearer` is the transport data protocol between endpoints, can be `BLE_Mesh.PROV_ADV` and/or `BLE_Mesh.PROV_GATT`. + +### BLE_Mesh.reset_node_prov() + +Resets the Node Provisioning information. + +### BLE_Mesh.create_element(*, primary, feature=0, beacon=true, ttl=7) + +This API creates a new BLE_Mesh_Element object. The BLE_Mesh_Element on concept level is equivalent to the Element in the BLE Mesh terminology. + +* `primary` shows whether this new Element will act as the Primary Element of the Node. When a Primary Element is created, the corresponding Configuration Server Model is also automatically created. There can only be 1 Primary Element per Node. +* `feature` shows what features to enable on the new Element. It is an ORED combination of `BLE_Mesh.RELAY`, `BLE_Mesh.LOW_POWER`, `BLE_Mesh.GATT_PROXY`, `BLE_Mesh.FRIEND` +* `ttl` is the default Time To Live value of the packets belonging to the new Element + +## Methods of BLE_Mesh_Element object + +### BLE_Mesh_Element.add_model(type=BLE_Mesh.GEN_ONOFF, server_client=BLE_Mesh.SERVER, *, callback=None, value=None, sen_min=-100, sen_max=100, sen_res=0.1) + +This API creates a new BLE_Mesh_Model object. The BLE_Mesh_Model on concept level is equivalent to the Model in the BLE Mesh terminology. + +* `type` is the type of the new Model. +* `server_client` shows whether the new Model will act as a Server or Client. +* `callback` is the user defined callback to call when any event happens on the Model. It accepts 3 parameters: `new_state`, `event`, `op_code`. The `new_state` is the corresponding state of BLE_Mesh_Model, the `event` and the `op_code` are belonging of the BLE Mesh packet received. +* `value` is the initial value represented by the Model. +* `sen_min` is the minimum value of Sensor State in case of Sensor Model. +* `sen_max` is the maximum value of Sensor State in case of Sensor Model. +* `sen_res` is the resolution of Sensor State in case of Sensor Model. + +## Methods of BLE_Mesh_Model object + +### BLE_Mesh_Model.get_state(addr=BLE_Mesh.ADDR_ALL_NODES, app_idx=0, state_type=None) + +Gets the State of the Sensor Model. If called from Server Model, returnes with State, in case of Client Model, it sends a Get Message, and returns State through the registered callback. + +* `addr` is the address of the remote Node to send the update message. +* `app_idx` is the index of one of the registered Application IDs to use when sending out the message. +* `state_type` is the type of Get State. + +### BLE_Mesh_Model.set_state(state, addr=BLE_Mesh.ADDR_ALL_NODES, app_idx=0, state_type=None) + +Sets the State of the Sensor Model. If called from Server Model, sets State directly, in case of Client Model, it sends a Set Message, and updates State. + +* `state` is the new value to update the current value with. +* `addr` is the address of the remote Node to send the update message. +* `app_idx` is the index of one of the registered Application IDs to use when sending out the message. +* `state_type` is the type of Set State. + +### BLE_Mesh_Model.status_state(addr=BLE_Mesh.ADDR_ALL_NODES, app_idx=0, state_type=None) + +Calling this function only makes sense when the BLE_Mesh_Model is a Server Model. It sends a Status message with the State to the Client Model(s). + +* `addr` is the address of the remote Node to send the update message. +* `app_idx` is the index of one of the registered Application IDs to use when sending out the message. +* `state_type` is the type of Status State. + +## Constants + +* Advertisement options: `BLE_Mesh.PROV_ADV`, `BLE_Mesh.PROV_GATT`, `BLE_Mesh.PROV_NONE` +* Features of an Element: `BLE_Mesh.RELAY`, `BLE_Mesh.LOW_POWER`, `BLE_Mesh.GATT_PROXY`, `BLE_Mesh.FRIEND` +* Authentication options: `BLE_Mesh.OOB_INPUT`, `BLE_Mesh.OOB_OUTPUT` +* Constants for Node addresses: `BLE_Mesh.ADDR_ALL_NODES`, `BLE_Mesh.ADDR_PUBLISH` +* Constants for Model - type: `BLE_Mesh.GEN_ONOFF`, `BLE_Mesh.GEN_LEVEL`, `BLE_Mesh.GEN_SENSOR`, `BLE_Mesh.GEN_SENSOR_SETUP` +* Constants for Model - server or client: `BLE_Mesh.SERVER`, `BLE_Mesh.CLIENT` +* Constants for Model - states: `BLE_Mesh.STATE_ONOFF`, `BLE_Mesh.STATE_LEVEL`, `BLE_Mesh.STATE_LEVEL_DELTA`, `BLE_Mesh.STATE_LEVEL_MOVE`, `BLE_Mesh.SEN_DESCRIPTOR`, `BLE_Mesh.SEN`, `BLE_Mesh.SEN_COLUMN`, `BLE_Mesh.SEN_SERIES`, `BLE_Mesh.SEN_SET_CADENCE`, `BLE_Mesh.SEN_SETTINGS`, `BLE_Mesh.SEN_SETTING` +* Constants for Provision Events: `BLE_Mesh.PROV_REGISTER_EVT`, `BLE_Mesh.PROV_ENABLE_EVT`, `BLE_Mesh.PROV_DISABLE_EVT`, `BLE_Mesh.LINK_OPEN_EVT`, `BLE_Mesh.LINK_CLOSE_EVT`, `BLE_Mesh.PROV_COMPLETE_EVT`, `BLE_Mesh.PROV_RESET_EVT`, `BLE_Mesh.PROV_OUTPUT_OOB_REQ_EVT`, `BLE_Mesh.PROV_INPUT_OOB_REQ_EVT` \ No newline at end of file diff --git a/content/firmwareapi/pycom/network/eth.md b/content/firmwareapi/pycom/network/eth.md index 3928631..73c3e9f 100644 --- a/content/firmwareapi/pycom/network/eth.md +++ b/content/firmwareapi/pycom/network/eth.md @@ -39,7 +39,9 @@ This function starts the Ethernet interface and enables the ethernet adapter. `hostname`: set the interface hostname -### eth.ifconfig(config=['dhcp' / configtuple]) +### eth.ifconfig([config={'dhcp' / configtuple}]) + +Get or set the interface configuration. Optionally specify the configuration parameter: diff --git a/content/firmwareapi/pycom/network/lte.md b/content/firmwareapi/pycom/network/lte.md index cc6c565..12ee482 100644 --- a/content/firmwareapi/pycom/network/lte.md +++ b/content/firmwareapi/pycom/network/lte.md @@ -26,7 +26,6 @@ The GPy and FiPy support both new LTE-M protocols: - Fipy/GPy v1.2 with Sequans old modem Firmwares < (39xxx)==> Supports 6 Bands (3, 4, 12, 13, 20, 28) -{{% /hint %}} ## AT Commands @@ -47,21 +46,42 @@ lte = LTE() ## Methods -### lte.init([carrier=standard]) +### lte.init([carrier='standard', psm_period_value=0, psm_period_unit=LTE.PSM_PERIOD_DISABLED, psm_active_value=0, psm_active_unit=LTE.PSM_ACTIVE_DISABLED]) -This method is used to set up the LTE subsystem. After a `deinit()` this method can take several seconds to return waiting for the LTE modem to start-up. Optionally specify a carrier name. The available options are: -* `'at&t'` -* `'verizon'` -* `'standard'` +This method is used to set up the LTE subsystem. Optionally specify +* `carrier name`. The available options are: + * `'at&t'` + * `'verizon'` + * `'standard'` +* `psm_period_value` : Configure at which period the device will connect to the network. Values from 0 to 31 are allowed +* `psm_period_unit` : Specify the _unit_ to be used for `psm_period_value`: + * `PSM_PERIOD_2S` + * `PSM_PERIOD_30S` + * `PSM_PERIOD_1M` + * `PSM_PERIOD_1H` + * `PSM_PERIOD_10H` + * `PSM_PERIOD_320H` + * `PSM_PERIOD_DISABLED`: Turn off the PSM mode. +* `psm_active_value` : Configure how long the device will be connected. Values from 0 to 31 are allowed. +* `psm_active_unit` : Specify the _unit_ for `psm_active_value`: + * `PSM_ACTIVE_2S` + * `PSM_ACTIVE_1M` + * `PSM_ACTIVE_6M` + * `PSM_ACTIVE_DISABLED`: turn off the PSM mode. +Multiply the `value` with the `unit` to get the actual active or sleeping times. -### lte.deinit([detach=True, reset = False]) +### lte.deinit([detach=True, reset=False]) Disables LTE modem completely. This reduces the power consumption to the minimum. Call this before entering deepsleep. * `detach` : detach from network. * `reset` : reset LTE modem. +### lte.psm() + +Queries the PSM timers. Returns a 5-tuple of the following structure: `(enabled, period_value, period_unit, active_value, active_unit)`. + ### lte.attach([band=None, apn=None, cid=None, type=LTE.IP, legacyattach=True]) Enable radio functionality and attach to the LTE network authorised by the inserted SIM card. Optionally specify: @@ -158,6 +178,11 @@ Check Network Coverage for UE device (i.e LTE modem). Returns: ## Constants -- `LTE.IP` : Internet Protocol IP +* `LTE.IP` : Internet Protocol IP -- `LTE.IPV4V6` : Internet protocol ver. 4/6 +* `LTE.IPV4V6` : Internet protocol ver. 4/6 + +* `PSM_PERIOD_2S`, `PSM_PERIOD_30S`, `PSM_PERIOD_1M`, `PSM_PERIOD_10M`, `PSM_PERIOD_1H`, `PSM_PERIOD_10H`, `PSM_PERIOD_320H`: Specify the unit for the PSM period to be 2 seconds, 30 seconds, 1 minute, 10 minutes, 1 hour, 10 hours, or 320 hours, respectively. +* `PSM_PERIOD_DISABLED`: Means turning PSM off. +* `PSM_ACTIVE_2S`, `PSM_ACTIVE_1M`, `PSM_ACTIVE_6M`: Specify the unit for the PSM active duration to be 2 seconds, 1 minute, or 6 minutes, respectively. +* `PSM_ACTIVE_DISABLED`: Means turning PSM off. diff --git a/content/firmwareapi/pycom/network/wlan.md b/content/firmwareapi/pycom/network/wlan.md index c831ac2..3b7b552 100644 --- a/content/firmwareapi/pycom/network/wlan.md +++ b/content/firmwareapi/pycom/network/wlan.md @@ -39,65 +39,50 @@ print(wlan.ifconfig()) ## Constructors -### class network.WLAN(id=0, ...) +### class network.WLAN([id=0], ...) -Create a WLAN object, and optionally configure it. See [`init`](../wlan#wlan-init-mode-ssid-none-auth-none-channel-1-antenna-none-power_save-false-hidden-false) for params of configuration. +Create a WLAN object, and optionally configure it. See init for params of configuration. -{{% hint style="info" %}} -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 initialised it will do the same as the other constructors an will initialise it with default values. -{{% /hint %}} +> The WLAN constructor is special in the sense that if no arguments 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 initialised it will do the same as the other constructors an will initialise it with default values. ## Methods -#### wlan.init(mode, \* , ssid=None, auth=None, channel=1, antenna=None, power\_save=False, hidden=False, bandwidth=HT40, max\_tx\_pwr=20, country=CN) +#### wlan.init(mode, [ssid=None, auth=None, channel=1, antenna=WLAN.INT_ANT, power_save=False, hidden=False, bandwidth=HT40, max_tx_pwr=20, country=NA, protocol=(1,1,1)]) Set or get the WiFi network processor configuration. Arguments are: -* `mode` can be either `WLAN.STA`, `WLAN.AP`, or `WLAN.STA_AP`. -* `ssid` is a string with the SSID name. Only needed when mode is `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. - * If `sec` is `WLAN.WEP` the key must be a string representing hexadecimal values (e.g. `ABC1DE45BF`). Only needed when mode is `WLAN.AP`. -* `channel` a number in the range 1-11. Only needed when mode is `WLAN.AP`. -* `antenna` selects between the internal and the external antenna. Can be either `WLAN.INT_ANT`, `WLAN.EXT_ANT`. With our development boards it defaults to using the internal antenna, but in the case of an OEM module, the antenna pin (`P12`) is not used, so it's free to be - - used for other things. - -* `power_save` enables or disables power save functions in `STA` mode. -* `hidden` only valid in `WLAN.AP` mode to create an access point with a hidden SSID when set to `True`. -* `bandwidth` is the Bandwidth to use, either 20MHz or 40 MHz , use `HT20` or `HT40` -* `max_tx_pwr` is the maximum WiFi Tx power allowed. see `WLAN.max_tx_power()` for more details +* `mode`: can be either: + * `WLAN.STA`: Station mode, connect to a WiFinetwork + * `WLAN.AP`: Access Point mode, create a WiFi network. You _must_ specify the `ssid` + * `WLAN.STA_AP`: Both Station and Access Point mode are active. +* `ssid`: a string with the SSID name. +* `auth`: a tuple with `(sec, key)`. Security can be one of the following. The key is a string with the network password. + * `None`: + * `WLAN.WEP`: Using this in `WLAN.AP`, the key must be a string of hexadecimal values. + * `WLAN.WPA` + * `WLAN.WPA2` + * `WLAN.WPA2_ENT`: this will use the following format: `(sec, username, password)` +* `channel`: a number in the range 1-11. Only needed when mode is `WLAN.AP`. +* `antenna`: select between the internal and the external antenna. With our development boards it defaults to using the on-board antenna. Value can be either: + * `WLAN.INT_ANT` + * `WLAN.EXT_ANT` +* `power_save` enables or disables power save functions in `WLAN.STA` mode. +* `hidden`: create a hidden SSID when set to `True`. only valid in `WLAN.AP` mode. +* `bandwidth` is the Bandwidth to use, either: + * `HT20`: 20MHz + * `HT40`: 40MHz +* `max_tx_pwr` is the maximum WiFi TX power allowed. see `WLAN.max_tx_power()` for more details * `country` tuple representing the country configuration parameters. see `WLAN.country()` for more details +* `protocol` tuple representing the protocol. see `WLAN.wifi_protocol()` for more details -For example, you can do: - -```python -# 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 - -```python -# configure as an station -wlan.init(mode=WLAN.STA) -``` - -{{% hint style="info" %}} -To use an external antenna, set `P12 as output pin.` - -```python - -Pin('P12', mode=Pin.OUT)(True) -``` -{{% /hint %}} ### wlan.deinit() Disables the WiFi radio. -### wlan.connect(ssid, \* , auth=None, bssid=None, timeout=None, ca\_certs=None, keyfile=None, certfile=None, identity=None, hostname=None) +### wlan.connect(ssid, [auth=None, bssid=None, timeout=None, ca_certs=None, keyfile=None, certfile=None, identity=None, hostname=None]) Connect to a wifi access point using the given SSID, and other security parameters. @@ -112,11 +97,10 @@ Connect to a wifi access point using the given SSID, and other security paramete * `identity` is only used in case of `WLAN.WPA2_ENT` security. Needed by the server. * `hostname` is the name of the host connecting to the AP. Max length of name string is 32 Bytes -{{% hint style="info" %}} -The ESP32 only handles certificates with `pkcs8` format (but not the "Traditional SSLeay RSAPrivateKey" format). The private key should be RSA coded with 2048 bits at maximum. -{{% /hint %}} +> The ESP32 only handles certificates with `pkcs8` format (but not the "Traditional SSLeay RSAPrivateKey" format). The private key should be RSA coded with 2048 bits at maximum. -#### wlan.scan(\[ssid=NULL, bssid=NULL, channel=0, show\_hidden=False, type=WLAN.SCAN\_ACTIVE, scantime=120ms\]) + +### wlan.scan([ssid=NULL, bssid=NULL, channel=0, show_hidden=False, type=WLAN.SCAN_ACTIVE, scantime=120ms]) Performs a network scan and returns a list of named tuples with (ssid, bssid, sec, channel, rssi). When no config args passed scan will be performed with default configurations. @@ -151,7 +135,7 @@ Disconnect from the WiFi access point. 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. -### wlan.ifconfig(id=0, config=\['dhcp' or configtuple\]) +### wlan.ifconfig(id=0, config=['dhcp' or configtuple]) When `id` is 0, the configuration will be get/set on the Station interface. When `id` is 1 the configuration will be done for the AP interface. @@ -161,15 +145,12 @@ If `dhcp` is passed as a parameter then the DHCP client is enabled and the IP pa If the 4-tuple config is given then a static IP is configured. For instance: -```python -wlan.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) -``` -### wlan.mode(\[mode\]) +### wlan.mode([mode]) Get or set the WLAN mode. -### wlan.ssid(\[ssid\]) +### wlan.ssid([ssid]) Get or set the SSID (Set SSID of AP). @@ -181,11 +162,11 @@ In case of mode = `WLAN.STA_AP` this method can get the ssid of board's own AP p _\_ -### wlan.auth(\[auth\]) +### wlan.auth([auth]) Get or set the authentication type when in AP mode. -### wlan.channel(\[channel\]) +### wlan.channel([channel]) _In AP mode:_ @@ -197,11 +178,12 @@ _In STA mode:_ _Note: Setting Channel in STA mode is only Allowed in Promiscuous mode_ -### wlan.antenna(\[antenna\]) +### wlan.antenna([antenna]) -Get or set the antenna type (external or internal). +Get or set the antenna type (external or internal). Value can be: -### wlan.mac(\[mac, mode\]) + +### wlan.mac([mac, mode]) when no arguments are passed a 6-byte long `bytes` tuple object with the WiFI MAC address of both Wifi Station mode and Acces Point mode @@ -219,13 +201,15 @@ _Note: STA and AP cannot have the Same Mac Address_ ### wlan.bandwidth() -Set the bandwidth of the wifi, either 20 MHz or 40 MHz can be configured, use constants `HT20` or `HT40` +Set the bandwidth of the wifi, either 20 MHz or 40 MHz can be configured, use constants: +* `HT20`: 20MHz +* `HT40`: 40MHz ### wlan.hostname() Set the Host name of the device connecting to the AP in case of Wifi `mode=WLAN.STA`, in case of `mode=WLAN.AP` this is the name of the host hosting the AP. Max length of name string is 32 Bytes -### wlan.ap\_sta\_list() +### wlan.ap_sta_list() Gets an info list of all stations connected to the board's AP. @@ -233,7 +217,12 @@ Info returned is a list of tuples containning (\[mac address of connected STA\], Protocol types are either : `WLAN.PHY_11_B`, `WLAN.PHY_11_G`, `WLAN.PHY_11_N` or `WLAN.PHY_LOW_RATE` -### wlan.max\_tx\_power(\[power\]) +### wlan.ap_tcpip_sta_list() + +This API returns with a list of the devices connected to the Pycom board when it is in AP mode. +Each element of the returned list is a tuple, containing the MAC address and IP address of the device. + +### wlan.max_tx_power([power]) Gets or Sets the maximum allowable transmission power for wifi. @@ -254,7 +243,7 @@ Values passed in power are mapped to transmit power levels as follows: * \[8, 19\]: level5 - 11dBm * \[-128, 7\]: level5 - 14dBm -### wlan.country(\[country, schan, nchan, max\_tx\_pwr, policy\]) +### wlan.country([country, schan, nchan, max_tx_pwr, policy]) Gets or set s Country configuration parameters for wifi. @@ -264,15 +253,16 @@ Gets or set s Country configuration parameters for wifi. * `max_tx_pwr` Maximum transmission power allowed. see `WLAN.max_tx_power()` for more details. * `policy` Is the method when setting country configuration for `WLAN.COUNTRY_POL_AUTO` in STA mode the wifi will aquire the same country config of the connected AP, for `WLAN.COUNTRY_POL_MAN` the configured country parameters will take effect regardless of Connected AP. -### wlan.joined\_ap\_info() +### wlan.joined_ap_info() Returns a tuple with (bssid, ssid, primary channel, rssi, Authorization method, wifi standard used) of the connected AP in case of STA mode. -### wlan.wifi\_protocol(\[(bool PHY11\_\_B, bool PHY11\_G, bool PHY11\_N)\]) +### wlan.wifi_protocol([(bool PHY11_B, bool PHY11_G, bool PHY11_N)\]) -Sets or gets Wifi Protocol supported. -### wlan.send\_raw(Buffer, interface=STA, use\_sys\_seq=True) +Sets or gets Wifi Protocol supported. Sets or gets Wifi Protocol supported in (`PHY_11_B`,`PHY_11_G`,`PHY_11_N`) format. Currently 802.11b or 802.11bg or 802.11bgn mode is available. + +### wlan.send_raw(Buffer, interface=STA, use_sys_seq=True) Send raw data through the Wifi Interface. @@ -288,7 +278,7 @@ Register a user callback function `handler` to be called once any of the `trigge For trigger events see `Constants` section. -### wlan.promiscuous(\[bool\]) +### wlan.promiscuous([bool]) * To enable Promiscuous mode `WLAN.promiscuous(True)` should be called, and `WLAN.promiscuous(False)` for disabling * To get current mode setting call function with empty args @@ -325,17 +315,17 @@ wlan.promiscuous(True) This function will return an integer object as mask for triggered events. -### wlan.wifi\_packet() +### wlan.wifi_packet() This function will return a tuble with Wifi packet info captured in promiscuous mode. -### wlan.ctrl\_pkt\_filter(\[int\]) +### wlan.ctrl_pkt_filter([int]) This function is used to set the filter mask for Wifi control packets in promiscuous mode. for Filter masks, see `Constants` section. To get the current Filter mask, call the function with empty args. -### wlan.smartConfig\(\) +### wlan.smartConfig() Start SmartConfig operation, the smartConfig is a provisioning technique that enables setting Wifi credentials for station mode wirelessly via mobile app. @@ -344,10 +334,12 @@ Start SmartConfig operation, the smartConfig is a provisioning technique that en - Use mobile App (ESP touch or Pycom App) to set ssid and password for the AP - You can register a callback to be triggered when smart Config is Finesed successfuly or timedout. -### wlan.Connected\_ap\_pwd() +### wlan.Connected_ap_pwd() Get the password of AP the Device is connected to. + + ## Constants * WLAN mode: `WLAN.STA`, `WLAN.AP`, `WLAN.STA_AP`