src/eric7/MicroPython/Devices/EspDevices.py

# -*- coding: utf-8 -*-

# Copyright (c) 2019 - 2023 Detlev Offenbach <detlev@die-offenbachs.de>
#

"""
Module implementing the device interface class for ESP32 and ESP8266 based
boards.
"""

import ast
import binascii
import json
import os

from PyQt6.QtCore import QCoreApplication, QProcess, QUrl, pyqtSlot
from PyQt6.QtNetwork import QNetworkReply, QNetworkRequest
from PyQt6.QtWidgets import QDialog, QMenu

from eric7 import Globals, Preferences
from eric7.EricGui.EricOverrideCursor import EricOverrideCursor
from eric7.EricWidgets import EricMessageBox
from eric7.EricWidgets.EricApplication import ericApp
from eric7.EricWidgets.EricProcessDialog import EricProcessDialog
from eric7.SystemUtilities import PythonUtilities

from ..MicroPythonWidget import HAS_QTCHART
from . import FirmwareGithubUrls
from .DeviceBase import BaseDevice


class EspDevice(BaseDevice):
    """
    Class implementing the device for ESP32 and ESP8266 based boards.
    """

    def __init__(self, microPythonWidget, deviceType, parent=None):
        """
        Constructor

        @param microPythonWidget reference to the main MicroPython widget
        @type MicroPythonWidget
        @param deviceType device type assigned to this device interface
        @type str
        @param parent reference to the parent object
        @type QObject
        """
        super().__init__(microPythonWidget, deviceType, parent)

        self.__createEsp32Submenu()

        self.__statusTranslations = {
            200: self.tr("beacon timeout"),
            201: self.tr("no matching access point found"),
            202: self.tr("authentication failed"),
            203: self.tr("association failed"),
            204: self.tr("handshake timeout"),
            1000: self.tr("idle"),
            1001: self.tr("connecting"),
            1010: self.tr("connected"),
        }
        self.__securityTranslations = {
            0: self.tr("open", "open WiFi network"),
            1: "WEP",
            2: "WPA",
            3: "WPA2",
            4: "WPA/WPA2",
            5: "WPA2 (CCMP)",
            6: "WPA3",
            7: "WPA2/WPA3",
        }

    def setButtons(self):
        """
        Public method to enable the supported action buttons.
        """
        super().setButtons()

        self.microPython.setActionButtons(
            run=True, repl=True, files=True, chart=HAS_QTCHART
        )

    def forceInterrupt(self):
        """
        Public method to determine the need for an interrupt when opening the
        serial connection.

        @return flag indicating an interrupt is needed
        @rtype bool
        """
        return True

    def deviceName(self):
        """
        Public method to get the name of the device.

        @return name of the device
        @rtype str
        """
        return self.tr("ESP8266, ESP32")

    def canStartRepl(self):
        """
        Public method to determine, if a REPL can be started.

        @return tuple containing a flag indicating it is safe to start a REPL
            and a reason why it cannot.
        @rtype tuple of (bool, str)
        """
        return True, ""

    def canStartPlotter(self):
        """
        Public method to determine, if a Plotter can be started.

        @return tuple containing a flag indicating it is safe to start a
            Plotter and a reason why it cannot.
        @rtype tuple of (bool, str)
        """
        return True, ""

    def canRunScript(self):
        """
        Public method to determine, if a script can be executed.

        @return tuple containing a flag indicating it is safe to start a
            Plotter and a reason why it cannot.
        @rtype tuple of (bool, str)
        """
        return True, ""

    def runScript(self, script):
        """
        Public method to run the given Python script.

        @param script script to be executed
        @type str
        """
        pythonScript = script.split("\n")
        self.sendCommands(pythonScript)

    def canStartFileManager(self):
        """
        Public method to determine, if a File Manager can be started.

        @return tuple containing a flag indicating it is safe to start a
            File Manager and a reason why it cannot.
        @rtype tuple of (bool, str)
        """
        return True, ""

    def __createEsp32Submenu(self):
        """
        Private method to create the ESP32 submenu.
        """
        self.__espMenu = QMenu(self.tr("ESP32 Functions"))

        self.__showMpyAct = self.__espMenu.addAction(
            self.tr("Show MicroPython Versions"), self.__showFirmwareVersions
        )
        self.__espMenu.addSeparator()
        self.__eraseFlashAct = self.__espMenu.addAction(
            self.tr("Erase Flash"), self.__eraseFlash
        )
        self.__flashMpyAct = self.__espMenu.addAction(
            self.tr("Flash MicroPython Firmware"), self.__flashMicroPython
        )
        self.__espMenu.addSeparator()
        self.__flashAdditionalAct = self.__espMenu.addAction(
            self.tr("Flash Additional Firmware"), self.__flashAddons
        )
        self.__espMenu.addSeparator()
        self.__backupAct = self.__espMenu.addAction(
            self.tr("Backup Firmware"), self.__backupFlash
        )
        self.__restoreAct = self.__espMenu.addAction(
            self.tr("Restore Firmware"), self.__restoreFlash
        )
        self.__espMenu.addSeparator()
        self.__chipIdAct = self.__espMenu.addAction(
            self.tr("Show Chip ID"), self.__showChipID
        )
        self.__flashIdAct = self.__espMenu.addAction(
            self.tr("Show Flash ID"), self.__showFlashID
        )
        self.__macAddressAct = self.__espMenu.addAction(
            self.tr("Show MAC Address"), self.__showMACAddress
        )
        self.__espMenu.addSeparator()
        self.__resetAct = self.__espMenu.addAction(
            self.tr("Reset Device"), self.__resetDevice
        )
        self.__espMenu.addSeparator()
        self.__espMenu.addAction(self.tr("Install 'esptool.py'"), self.__installEspTool)

    def addDeviceMenuEntries(self, menu):
        """
        Public method to add device specific entries to the given menu.

        @param menu reference to the context menu
        @type QMenu
        """
        connected = self.microPython.isConnected()
        linkConnected = self.microPython.isLinkConnected()

        self.__showMpyAct.setEnabled(connected)
        self.__eraseFlashAct.setEnabled(not linkConnected)
        self.__flashMpyAct.setEnabled(not linkConnected)
        self.__flashAdditionalAct.setEnabled(not linkConnected)
        self.__backupAct.setEnabled(not linkConnected)
        self.__restoreAct.setEnabled(not linkConnected)
        self.__chipIdAct.setEnabled(not linkConnected)
        self.__flashIdAct.setEnabled(not linkConnected)
        self.__macAddressAct.setEnabled(not linkConnected)
        self.__resetAct.setEnabled(connected or not linkConnected)

        menu.addMenu(self.__espMenu)

    def hasFlashMenuEntry(self):
        """
        Public method to check, if the device has its own flash menu entry.

        @return flag indicating a specific flash menu entry
        @rtype bool
        """
        return True

    @pyqtSlot()
    def __eraseFlash(self):
        """
        Private slot to erase the device flash memory.
        """
        eraseFlash(self.microPython.getCurrentPort())

    @pyqtSlot()
    def __flashMicroPython(self):
        """
        Private slot to flash a MicroPython firmware to the device.
        """
        flashPythonFirmware(self.microPython.getCurrentPort())

    @pyqtSlot()
    def __flashAddons(self):
        """
        Private slot to flash some additional firmware images.
        """
        flashAddonFirmware(self.microPython.getCurrentPort())

    @pyqtSlot()
    def __backupFlash(self):
        """
        Private slot to backup the currently flashed firmware.
        """
        from .EspDialogs.EspBackupRestoreFirmwareDialog import (
            EspBackupRestoreFirmwareDialog,
        )

        dlg = EspBackupRestoreFirmwareDialog(backupMode=True)
        if dlg.exec() == QDialog.DialogCode.Accepted:
            chip, flashSize, baudRate, flashMode, firmware = dlg.getData()
            flashArgs = [
                "-u",
                "-m",
                "esptool",
                "--chip",
                chip,
                "--port",
                self.microPython.getCurrentPort(),
                "--baud",
                baudRate,
                "read_flash",
                "0x0",
                flashSize,
                firmware,
            ]
            dlg = EricProcessDialog(
                self.tr("'esptool read_flash' Output"),
                self.tr("Backup Firmware"),
                showProgress=True,
            )
            res = dlg.startProcess(PythonUtilities.getPythonExecutable(), flashArgs)
            if res:
                dlg.exec()

    @pyqtSlot()
    def __restoreFlash(self):
        """
        Private slot to restore a previously saved firmware.
        """
        from .EspDialogs.EspBackupRestoreFirmwareDialog import (
            EspBackupRestoreFirmwareDialog,
        )

        dlg = EspBackupRestoreFirmwareDialog(backupMode=False)
        if dlg.exec() == QDialog.DialogCode.Accepted:
            chip, flashSize, baudRate, flashMode, firmware = dlg.getData()
            flashArgs = [
                "-u",
                "-m",
                "esptool",
                "--chip",
                chip,
                "--port",
                self.microPython.getCurrentPort(),
                "--baud",
                baudRate,
                "write_flash",
            ]
            if flashMode:
                flashArgs.extend(
                    [
                        "--flash_mode",
                        flashMode,
                    ]
                )
            if bool(flashSize):
                flashArgs.extend(
                    [
                        "--flash_size",
                        flashSize,
                    ]
                )
            flashArgs.extend(
                [
                    "0x0",
                    firmware,
                ]
            )
            dlg = EricProcessDialog(
                self.tr("'esptool write_flash' Output"),
                self.tr("Restore Firmware"),
                showProgress=True,
            )
            res = dlg.startProcess(PythonUtilities.getPythonExecutable(), flashArgs)
            if res:
                dlg.exec()

    @pyqtSlot()
    def __showFirmwareVersions(self):
        """
        Private slot to show the firmware version of the connected device and the
        available firmware version.
        """
        if self.microPython.isConnected():
            if self._deviceData["mpy_name"] == "micropython":
                url = QUrl(FirmwareGithubUrls["micropython"])
            elif self._deviceData["mpy_name"] == "circuitpython":
                url = QUrl(FirmwareGithubUrls["circuitpython"])
            else:
                EricMessageBox.critical(
                    None,
                    self.tr("Show MicroPython Versions"),
                    self.tr(
                        """The firmware of the connected device cannot be"""
                        """ determined or the board does not run MicroPython"""
                        """ or CircuitPython. Aborting..."""
                    ),
                )
                return

            ui = ericApp().getObject("UserInterface")
            request = QNetworkRequest(url)
            reply = ui.networkAccessManager().head(request)
            reply.finished.connect(lambda: self.__firmwareVersionResponse(reply))

    @pyqtSlot(QNetworkReply)
    def __firmwareVersionResponse(self, reply):
        """
        Private slot handling the response of the latest version request.

        @param reply reference to the reply object
        @type QNetworkReply
        """
        latestUrl = reply.url().toString()
        tag = latestUrl.rsplit("/", 1)[-1]
        while tag and not tag[0].isdecimal():
            # get rid of leading non-decimal characters
            tag = tag[1:]
        latestVersion = Globals.versionToTuple(tag)

        if self._deviceData["mpy_version"] == "unknown":
            currentVersionStr = self.tr("unknown")
            currentVersion = (0, 0, 0)
        else:
            currentVersionStr = self._deviceData["mpy_version"]
            currentVersion = Globals.versionToTuple(currentVersionStr)

        if self._deviceData["mpy_name"] == "circuitpython":
            kind = "CircuitPython"
        elif self._deviceData["mpy_name"] == "micropython":
            kind = "MicroPython"

        msg = self.tr(
            "<h4>{0} Version Information</h4>"
            "<table>"
            "<tr><td>Installed:</td><td>{1}</td></tr>"
            "<tr><td>Available:</td><td>{2}</td></tr>"
            "</table>"
        ).format(kind, currentVersionStr, tag)
        if currentVersion < latestVersion:
            msg += self.tr("<p><b>Update available!</b></p>")

        EricMessageBox.information(
            None,
            self.tr("{0} Version").format(kind),
            msg,
        )

    @pyqtSlot()
    def __showChipID(self):
        """
        Private slot to show the ID of the ESP chip.
        """
        args = [
            "-u",
            "-m",
            "esptool",
            "--port",
            self.microPython.getCurrentPort(),
            "chip_id",
        ]
        dlg = EricProcessDialog(
            self.tr("'esptool chip_id' Output"), self.tr("Show Chip ID")
        )
        res = dlg.startProcess(PythonUtilities.getPythonExecutable(), args)
        if res:
            dlg.exec()

    @pyqtSlot()
    def __showFlashID(self):
        """
        Private slot to show the ID of the ESP flash chip.
        """
        args = [
            "-u",
            "-m",
            "esptool",
            "--port",
            self.microPython.getCurrentPort(),
            "flash_id",
        ]
        dlg = EricProcessDialog(
            self.tr("'esptool flash_id' Output"), self.tr("Show Flash ID")
        )
        res = dlg.startProcess(PythonUtilities.getPythonExecutable(), args)
        if res:
            dlg.exec()

    @pyqtSlot()
    def __showMACAddress(self):
        """
        Private slot to show the MAC address of the ESP chip.
        """
        args = [
            "-u",
            "-m",
            "esptool",
            "--port",
            self.microPython.getCurrentPort(),
            "read_mac",
        ]
        dlg = EricProcessDialog(
            self.tr("'esptool read_mac' Output"), self.tr("Show MAC Address")
        )
        res = dlg.startProcess(PythonUtilities.getPythonExecutable(), args)
        if res:
            dlg.exec()

    @pyqtSlot()
    def __resetDevice(self):
        """
        Private slot to reset the connected device.
        """
        if self.microPython.isConnected():
            self.microPython.deviceInterface().execute(
                "import machine\nmachine.reset()\n", mode=self._submitMode
            )
        else:
            # perform a reset via esptool using flash_id command ignoring
            # the output
            args = [
                "-u",
                "-m",
                "esptool",
                "--port",
                self.microPython.getCurrentPort(),
                "flash_id",
            ]
            proc = QProcess()
            proc.start(PythonUtilities.getPythonExecutable(), args)
            procStarted = proc.waitForStarted(10000)
            if procStarted:
                proc.waitForFinished(10000)

    @pyqtSlot()
    def __installEspTool(self):
        """
        Private slot to install the esptool package via pip.
        """
        pip = ericApp().getObject("Pip")
        pip.installPackages(
            ["esptool"], interpreter=PythonUtilities.getPythonExecutable()
        )

    def getDocumentationUrl(self):
        """
        Public method to get the device documentation URL.

        @return documentation URL of the device
        @rtype str
        """
        return Preferences.getMicroPython("MicroPythonDocuUrl")

    def getFirmwareUrl(self):
        """
        Public method to get the device firmware download URL.

        @return firmware download URL of the device
        @rtype str
        """
        return Preferences.getMicroPython("MicroPythonFirmwareUrl")

    ##################################################################
    ## time related methods below
    ##################################################################

    def _getSetTimeCode(self):
        """
        Protected method to get the device code to set the time.

        Note: This method must be implemented in the various device specific
        subclasses.

        @return code to be executed on the connected device to set the time
        @rtype str
        """
        # rtc_time[0] - year    4 digit
        # rtc_time[1] - month   1..12
        # rtc_time[2] - day     1..31
        # rtc_time[3] - weekday 1..7 1=Monday
        # rtc_time[4] - hour    0..23
        # rtc_time[5] - minute  0..59
        # rtc_time[6] - second  0..59
        # rtc_time[7] - yearday 1..366
        # rtc_time[8] - isdst   0, 1, or -1

        # The machine.RTC.init() (ESP32) and machine.rtc.datetime() (ESP8266) functions
        # take the arguments in the order:
        # (year, month, day, weekday, hour, minute, second, subseconds)
        # __IGNORE_WARNING_M891__
        # https://docs.micropython.org/en/latest/library/machine.RTC.html#machine-rtc
        #
        # LoBo variant of MPy deviates.
        return """
def set_time(rtc_time):
    import machine
    rtc = machine.RTC()
    try:
        rtc.datetime(rtc_time[:7] + (0,))
    except Exception:
        import os
        if 'LoBo' in os.uname()[0]:
            clock_time = rtc_time[:3] + rtc_time[4:7] + (rtc_time[3], rtc_time[7])
        else:
            clock_time = rtc_time[:7] + (0,)
        rtc.init(clock_time)
"""

    ##################################################################
    ## Methods below implement WiFi related methods
    ##################################################################

    def hasWifi(self):
        """
        Public method to check the availability of WiFi.

        @return tuple containing a flag indicating the availability of WiFi
            and the WiFi type (esp32)
        @rtype tuple of (bool, str)
        """
        return True, "esp32"

    def getWifiData(self):
        """
        Public method to get data related to the current WiFi status.

        @return tuple of three dictionaries containing the WiFi status data
            for the WiFi client, access point and overall data
        @rtype tuple of (dict, dict, dict)
        @exception OSError raised to indicate an issue with the device
        """
        command = """
def wifi_status():
    import ubinascii
    import ujson
    import network

    wifi = network.WLAN(network.STA_IF)
    station = {
        'active': wifi.active(),
        'connected': wifi.isconnected(),
        'status': wifi.status(),
        'ifconfig': wifi.ifconfig(),
        'mac': ubinascii.hexlify(wifi.config('mac'), ':').decode(),
    }
    if wifi.active():
        try:
            station['txpower'] = wifi.config('txpower')
        except ValueError:
            pass
    print(ujson.dumps(station))

    wifi = network.WLAN(network.AP_IF)
    ap = {
        'active': wifi.active(),
        'connected': wifi.isconnected(),
        'status': wifi.status(),
        'ifconfig': wifi.ifconfig(),
        'mac': ubinascii.hexlify(wifi.config('mac'), ':').decode(),
        'channel': wifi.config('channel'),
        'essid': wifi.config('essid'),
    }
    if wifi.active():
        try:
            ap['txpower'] = wifi.config('txpower')
        except ValueError:
            pass
    print(ujson.dumps(ap))

    overall = {
        'active': station['active'] or ap['active']
    }
    print(ujson.dumps(overall))

wifi_status()
del wifi_status
"""

        out, err = self._interface.execute(command, mode=self._submitMode)
        if err:
            raise OSError(self._shortError(err))

        stationStr, apStr, overallStr = out.decode("utf-8").splitlines()
        station = json.loads(stationStr)
        ap = json.loads(apStr)
        overall = json.loads(overallStr)
        try:
            station["status"] = self.__statusTranslations[station["status"]]
        except KeyError:
            station["status"] = str(station["status"])
        try:
            ap["status"] = self.__statusTranslations[ap["status"]]
        except KeyError:
            ap["status"] = str(ap["status"])
        return station, ap, overall

    def connectWifi(self, ssid, password):
        """
        Public method to connect a device to a WiFi network.

        @param ssid name (SSID) of the WiFi network
        @type str
        @param password password needed to connect
        @type str
        @return tuple containing the connection status and an error string
        @rtype tuple of (bool, str)
        """
        command = """
def connect_wifi(ssid, password):
    import network
    import ujson
    from time import sleep

    wifi = network.WLAN(network.STA_IF)
    wifi.active(False)
    wifi.active(True)
    wifi.connect(ssid, password)
    max_wait = 140
    while max_wait and wifi.status() == network.STAT_CONNECTING:
        max_wait -= 1
        sleep(0.1)
    status = wifi.status()
    print(ujson.dumps({{'connected': wifi.isconnected(), 'status': status}}))

connect_wifi({0}, {1})
del connect_wifi
""".format(
            repr(ssid),
            repr(password if password else ""),
        )

        with EricOverrideCursor():
            out, err = self._interface.execute(
                command, mode=self._submitMode, timeout=15000
            )
        if err:
            return False, err

        result = json.loads(out.decode("utf-8").strip())
        if result["connected"]:
            error = ""
        else:
            try:
                error = self.__statusTranslations[result["status"]]
            except KeyError:
                error = str(result["status"])

        return result["connected"], error

    def disconnectWifi(self):
        """
        Public method to disconnect a device from the WiFi network.

        @return tuple containing a flag indicating success and an error string
        @rtype tuple of (bool, str)
        """
        command = """
def disconnect_wifi():
    import network
    from time import sleep

    wifi = network.WLAN(network.STA_IF)
    wifi.disconnect()
    wifi.active(False)
    sleep(0.1)
    print(not wifi.isconnected())

disconnect_wifi()
del disconnect_wifi
"""

        out, err = self._interface.execute(command, mode=self._submitMode)
        if err:
            return False, err

        return out.decode("utf-8").strip() == "True", ""

    def writeCredentials(self, ssid, password):
        """
        Public method to write the given credentials to the connected device and modify
        the start script to connect automatically.

        @param ssid SSID of the network to connect to
        @type str
        @param password password needed to authenticate
        @type str
        @return tuple containing a flag indicating success and an error message
        @rtype tuple of (bool, str)
        """
        nvsCommand = """
def save_wifi_creds(ssid, password):
    import esp32

    nvs = esp32.NVS('wifi_creds')
    nvs.set_blob('ssid', ssid)
    nvs.set_blob('password', password)
    nvs.commit()

save_wifi_creds({0}, {1})
del save_wifi_creds
""".format(
            repr(ssid), repr(password) if password else "''"
        )
        bootCommand = """
def modify_boot():
    add = True
    try:
        with open('/boot.py', 'r') as f:
            for ln in f.readlines():
                if 'wifi_connect' in ln:
                    add = False
                    break
    except:
        pass
    if add:
        with open('/boot.py', 'a') as f:
            f.write('\\nimport wifi_connect\\n')
    print(True)

modify_boot()
del modify_boot
"""

        out, err = self._interface.execute(nvsCommand, mode=self._submitMode)
        if err:
            return False, self.tr("Error saving credentials: {0}").format(err)

        try:
            # copy auto-connect file
            self.put(
                os.path.join(
                    os.path.dirname(__file__), "MCUScripts", "esp32WiFiConnect.py"
                ),
                "/wifi_connect.py",
            )
        except OSError as err:
            return False, self.tr("Error saving auto-connect script: {0}").format(err)

        out, err = self._interface.execute(bootCommand, mode=self._submitMode)
        if err:
            return False, self.tr("Error modifying 'boot.py': {0}").format(err)

        return True, ""

    def removeCredentials(self):
        """
        Public method to remove the saved credentials from the connected device.

        @return tuple containing a flag indicating success and an error message
        @rtype tuple of (bool, str)
        """
        nvsCommand = """
def delete_wifi_creds():
    import esp32

    nvs = esp32.NVS('wifi_creds')
    try:
        nvs.erase_key('ssid')
        nvs.erase_key('password')
        nvs.commit()
    except OSError:
        pass

delete_wifi_creds()
del delete_wifi_creds
"""

        out, err = self._interface.execute(nvsCommand, mode=self._submitMode)
        if err:
            return False, self.tr("Error deleting credentials: {0}").format(err)

        return True, ""

    def checkInternet(self):
        """
        Public method to check, if the internet can be reached.

        @return tuple containing a flag indicating reachability and an error string
        @rtype tuple of (bool, str)
        """
        command = """
def check_internet():
    import network
    import socket

    wifi = network.WLAN(network.STA_IF)
    if wifi.isconnected():
        s = socket.socket()
        try:
            s.connect(socket.getaddrinfo('google.com', 80)[0][-1])
            s.close()
            print(True)
        except:
            print(False)
    else:
        print(False)

check_internet()
del check_internet
"""

        out, err = self._interface.execute(command, mode=self._submitMode)
        if err:
            return False, err

        return out.decode("utf-8").strip() == "True", ""

    def scanNetworks(self):
        """
        Public method to scan for available WiFi networks.

        @return tuple containing the list of available networks as a tuple of 'Name',
            'MAC-Address', 'channel', 'RSSI' and 'security' and an error string
        @rtype tuple of (list of tuple of (str, str, int, int, str), str)
        """
        command = """
def scan_networks():
    import network

    wifi = network.WLAN(network.STA_IF)
    active = wifi.active()
    if not active:
        wifi.active(True)
    network_list = wifi.scan()
    if not active:
        wifi.active(False)
    print(network_list)

scan_networks()
del scan_networks
"""

        out, err = self._interface.execute(
            command, mode=self._submitMode, timeout=15000
        )
        if err:
            return [], err

        networksList = ast.literal_eval(out.decode("utf-8"))
        networks = []
        for network in networksList:
            if network[0]:
                ssid = network[0].decode("utf-8")
                mac = binascii.hexlify(network[1], ":").decode("utf-8")
                channel = network[2]
                rssi = network[3]
                try:
                    security = self.__securityTranslations[network[4]]
                except KeyError:
                    security = self.tr("unknown ({0})").format(network[4])
                networks.append((ssid, mac, channel, rssi, security))

        return networks, ""

    def deactivateInterface(self, interface):
        """
        Public method to deactivate a given WiFi interface of the connected device.

        @param interface designation of the interface to be deactivated (one of 'AP'
            or 'STA')
        @type str
        @return tuple containg a flag indicating success and an error message
        @rtype tuple of (bool, str)
        @exception ValueError raised to indicate a wrong value for the interface type
        """
        if interface not in ("STA", "AP"):
            raise ValueError(
                "interface must be 'AP' or 'STA', got '{0}'".format(interface)
            )

        command = """
def deactivate():
    import network
    from time import sleep

    wifi = network.WLAN(network.{0}_IF)
    wifi.active(False)
    sleep(0.1)
    print(not wifi.active())

deactivate()
del deactivate
""".format(
            interface
        )

        out, err = self._interface.execute(command, mode=self._submitMode)
        if err:
            return False, err
        else:
            return out.decode("utf-8").strip() == "True", ""

    def startAccessPoint(self, ssid, security=None, password=None, ifconfig=None):
        """
        Public method to start the access point interface.

        @param ssid SSID of the access point
        @type str
        @param security security method (defaults to None)
        @type int (optional)
        @param password password (defaults to None)
        @type str (optional)
        @param ifconfig IPv4 configuration for the access point if not default
            (IPv4 address, netmask, gateway address, DNS server address)
        @type tuple of (str, str, str, str)
        @return tuple containing a flag indicating success and an error message
        @rtype tuple of (bool, str)
        """
        if security is None or password is None:
            security = 0
            password = ""
        if security > 4:
            security = 4  # security >4 cause an error thrown by the ESP32

        command = """
def start_ap(ssid, authmode, password, ifconfig):
    import network

    ap = network.WLAN(network.AP_IF)
    ap.active(False)
    if ifconfig:
        ap.ifconfig(ifconfig)
    ap.active(True)
    try:
        ap.config(ssid=ssid, authmode=authmode, password=password)
    except:
        ap.config(essid=ssid, authmode=authmode, password=password)

start_ap({0}, {1}, {2}, {3})
del start_ap
""".format(
            repr(ssid), security, repr(password), ifconfig
        )

        out, err = self._interface.execute(
            command, mode=self._submitMode, timeout=15000
        )
        if err:
            return False, err
        else:
            return True, ""

    def stopAccessPoint(self):
        """
        Public method to stop the access point interface.

        @return tuple containg a flag indicating success and an error message
        @rtype tuple of (bool, str)
        """
        return self.deactivateInterface("AP")

    def getConnectedClients(self):
        """
        Public method to get a list of connected clients.

        @return a tuple containing a list of tuples containing the client MAC-Address
            and the RSSI (if supported and available) and an error message
        @rtype tuple of ([(bytes, int)], str)
        """
        command = """
def get_stations():
    import network

    ap = network.WLAN(network.AP_IF)
    stations = ap.status('stations')
    print(stations)

get_stations()
del get_stations
"""

        out, err = self._interface.execute(
            command, mode=self._submitMode, timeout=10000
        )
        if err:
            return [], err

        clientsList = ast.literal_eval(out.decode("utf-8"))
        return clientsList, ""


def createDevice(microPythonWidget, deviceType, vid, pid, boardName, serialNumber):
    """
    Function to instantiate a MicroPython device object.

    @param microPythonWidget reference to the main MicroPython widget
    @type MicroPythonWidget
    @param deviceType device type assigned to this device interface
    @type str
    @param vid vendor ID
    @type int
    @param pid product ID
    @type int
    @param boardName name of the board
    @type str
    @param serialNumber serial number of the board
    @type str
    @return reference to the instantiated device object
    @rtype EspDevice
    """
    return EspDevice(microPythonWidget, deviceType)


################################################################################
## Functions below implement flashing related functionality needed elsewhere  ##
## as well.                                                                   ##
################################################################################


@pyqtSlot()
def eraseFlash(port):
    """
    Slot to erase the device flash memory.

    @param port name of the serial port device to be used
    @type str
    """
    ok = EricMessageBox.yesNo(
        None,
        QCoreApplication.translate("EspDevice", "Erase Flash"),
        QCoreApplication.translate(
            "EspDevice", """Shall the flash of the selected device really be erased?"""
        ),
    )
    if ok:
        flashArgs = [
            "-u",
            "-m",
            "esptool",
            "--port",
            port,
            "erase_flash",
        ]
        dlg = EricProcessDialog(
            QCoreApplication.translate("EspDevice", "'esptool erase_flash' Output"),
            QCoreApplication.translate("EspDevice", "Erase Flash"),
            showProgress=True,
        )
        res = dlg.startProcess(PythonUtilities.getPythonExecutable(), flashArgs)
        if res:
            dlg.exec()


@pyqtSlot()
def flashPythonFirmware(port):
    """
    Slot to flash a MicroPython firmware to the device.

    @param port name of the serial port device to be used
    @type str
    """
    from .EspDialogs.EspFirmwareSelectionDialog import EspFirmwareSelectionDialog

    dlg = EspFirmwareSelectionDialog()
    if dlg.exec() == QDialog.DialogCode.Accepted:
        chip, firmware, baudRate, flashMode, flashAddress = dlg.getData()
        flashArgs = [
            "-u",
            "-m",
            "esptool",
            "--chip",
            chip,
            "--port",
            port,
        ]
        if baudRate != "115200":
            flashArgs += ["--baud", baudRate]
        flashArgs.append("write_flash")
        if flashMode:
            flashArgs += ["--flash_mode", flashMode]
        flashArgs += [
            flashAddress,
            firmware,
        ]
        dlg = EricProcessDialog(
            QCoreApplication.translate("EspDevice", "'esptool write_flash' Output"),
            QCoreApplication.translate("EspDevice", "Flash µPy/CPy Firmware"),
            showProgress=True,
        )
        res = dlg.startProcess(PythonUtilities.getPythonExecutable(), flashArgs)
        if res:
            dlg.exec()


@pyqtSlot()
def flashAddonFirmware(port):
    """
    Slot to flash some additional firmware images.

    @param port name of the serial port device to be used
    @type str
    """
    from .EspDialogs.EspFirmwareSelectionDialog import EspFirmwareSelectionDialog

    dlg = EspFirmwareSelectionDialog(addon=True)
    if dlg.exec() == QDialog.DialogCode.Accepted:
        chip, firmware, baudRate, flashMode, flashAddress = dlg.getData()
        flashArgs = [
            "-u",
            "-m",
            "esptool",
            "--chip",
            chip,
            "--port",
            port,
        ]
        if baudRate != "115200":
            flashArgs += ["--baud", baudRate]
        flashArgs.append("write_flash")
        if flashMode:
            flashArgs += ["--flash_mode", flashMode]
        flashArgs += [
            flashAddress.lower(),
            firmware,
        ]
        dlg = EricProcessDialog(
            QCoreApplication.translate("EspDevice", "'esptool write_flash' Output"),
            QCoreApplication.translate("EspDevice", "Flash Additional Firmware"),
            showProgress=True,
        )
        res = dlg.startProcess(PythonUtilities.getPythonExecutable(), flashArgs)
        if res:
            dlg.exec()