esp8266fs.js

"use strict";

//------------------------------------------------------------------------------

Object.defineProperty(exports, "__esModule", { value: true });

//------------------------------------------------------------------------------

const childProcess = require("child_process");
const fs = require("fs");
const os = require("os");
const path = require("path");
const process = require("process");
const tmp = require("tmp");
const vscode = require("vscode");
const WinReg = require("winreg");

//==============================================================================
// #region Constants

    // --- VSCode Arduino Extension ---

const ARDUINO_CONFIG_FILE = path.join(".vscode", "arduino.json");

const PYTHON_PYTHONPATH = "python.pythonPath";                   // Python Executable

    // --- new items ---

const ESP8266FS_DATA_FILES        = "esp8266fs.dataFiles";       // Location of SPIFFS files
const ESP8266FS_PREFERENCES       = "esp8266fs.preferencesPath"; // Location of Arduino Preferences and Packages
const ESP8266FS_ARDUINO_USER_PATH = "esp8266fs.arduinoUserPath"; // Location of Ardiuno User Libraries
const ESP8266FS_SPIFFS_IMAGE      = "esp8266fs.spiffsImage";     // Packed SPIFFS file
const ESP8266FS_LOGLEVEL          = "esp8266fs.logLevel";        // Level of spew generated by this extension

const ESP8266FS_MKSPIFFS_EXECUTABLE  = "esp8266fs.mkspiffs.executable"; // MKSPIFFS Executable
const ESP8266FS_MKSPIFFS_DEBUG_LEVEL = "esp8266fs.mkspiffs.debugLevel"; // Value passed to MKSPIFFS Executable
const ESP8266FS_MKSPIFFS_ALL_FILES   = "esp8266fs.mkspiffs.allFiles";   // Value passed to MKSPIFFS Executable

const ESP8266FS_ESPTOOL_EXECUTABLE = "esp8266fs.esptool.executable"; // ESPTOOL Executable
const ESP8266FS_ESPTOOL_VERBOSITY  = "esp8266fs.esptool.verbosity";  // Value passed to ESPTOOL Executable

const ESP8266FS_ESPTOOL_PY_BEFORE   = "esp8266fs.esptool.before";         // Value passed to ESPTOOL.PY script
const ESP8266FS_ESPTOOL_PY_AFTER    = "esp8266fs.esptool.after";          // Value passed to ESPTOOL.PY script
const ESP8266FS_ESPTOOL_PY_NO_STUB  = "esp8266fs.esptool.no_stub";        // Value passed to ESPTOOL.PY script
const ESP8266FS_ESPTOOL_PY_TRACE    = "esp8266fs.esptool.trace";          // Value passed to ESPTOOL.PY script
const ESP8266FS_ESPTOOL_PY_SPI      = "esp8266fs.esptool.spi_connection"; // Value passed to ESPTOOL.PY script
const ESP8266FS_ESPTOOL_PY_COMPRESS = "esp8266fs.esptool.compress";       // Value passed to ESPTOOL.PY script
const ESP8266FS_ESPTOOL_PY_VERIFY   = "esp8266fs.esptool.verify";         // Value passed to ESPTOOL.PY script

const ESP8266FS_ESPOTA_PY        = "esp8266fs.espota.py";        // EspOTA Python script
const ESP8266FS_ESPOTA_ESP_PORT  = "esp8266fs.espota.esp.port";  // IP Port for ESP8266
const ESP8266FS_ESPOTA_HOST_IP   = "esp8266fs.espota.host.ip";   // IP Address for Host
const ESP8266FS_ESPOTA_HOST_PORT = "esp8266fs.espota.host.port"; // IP Port for Host
const ESP8266FS_ESPOTA_AUTH      = "esp8266fs.espota.auth";      // Authentication password for espota.py
const ESP8266FS_ESPOTA_DEBUG     = "esp8266fs.espota.debug";     // Enable debug output from espota.py

// #endregion

//==============================================================================
// #region Logging

const RESET    = "\u001b[0m";
const BOLD     = "\u001b[1m";

const RED      = "\u001b[31m";
const GREEN    = "\u001b[32m";
const YELLOW   = "\u001b[33m";
const BLUE     = "\u001b[34m";
const MAGENTA  = "\u001b[35m";
const CYAN     = "\u001b[36m";

const BOLD_RED = "\u001b[31;1m";

//------------------------------------------------------------------------------

let outputChannel = null;
let logLevel = "normal"; // "normal", "verbose", "silent", "debug"

function log(message, color)
{
    if (logLevel === "silent")
        return;

    if (color)
        console.log(`${color}${message}${RESET}`);
    else
        console.log(message);

    outputChannel.appendLine(message.replace(/\x1b\[[\d|\;]{1,4}m/g, ""));
    outputChannel.show();
}

//------------------------------------------------------------------------------

function logAnnounce(message)  { log(message, GREEN); }
function logUrgent(message)    { log(message, BOLD_RED); }
function logImportant(message) { log(message, RED); }
function logCommand(message)   { log(message, YELLOW); }
function logSpiffs(message)    { log(`  [SPIFFS] ${message}`, BLUE); }

//------------------------------------------------------------------------------

function logVerbose(message)
{
    if (logLevel === "verbose" || logLevel === "debug")
        log(message, MAGENTA);
}

//------------------------------------------------------------------------------

function logDebug(message)
{
    if (logLevel === "debug")
        log(message, CYAN);
}

//------------------------------------------------------------------------------

function showErrorMessage(message)
{
    const dismiss = { isCloseAffordance: true, title: "Dismiss" };

    vscode.window.showErrorMessage(message, dismiss);
}

//------------------------------------------------------------------------------

function showWarningMessage(message)
{
    vscode.window.showWarningMessage(message);
}

//------------------------------------------------------------------------------

function showInformationMessage(message)
{
    vscode.window.showInformationMessage(message);
}

// #endregion

//==============================================================================
// #region Helper functions

function stringToInt(value)
{
    return parseInt(value, value.match(/^0x/i) ? 16 : 10);
}

//------------------------------------------------------------------------------

function toHex(decimal, width = 4)
{
    return ("0".repeat(width) + (Number(decimal).toString(16))).slice(-width).toUpperCase();
}

//------------------------------------------------------------------------------

function makeOsPath(dir)
{
    dir = dir.replace(/\\/g, "/");

    if (dir.indexOf(" ") != -1)
        dir = `"${dir}"`;

    return dir;
}

// #endregion

//==============================================================================
// #region Utility functions

function getVscodeConfigValue(key) {
    return vscode.workspace.getConfiguration().get(key);
}

//------------------------------------------------------------------------------

function getOS() { return os.platform(); }

//------------------------------------------------------------------------------

function program(name) {
    return (getOS() === "win32" && name.indexOf(".") == -1)
        ? (name + ".exe")
        : name;
}

//------------------------------------------------------------------------------

function runCommand(command, args) {
    logVerbose("Running: " + command + " " + args.join(" "));

    const spawn = childProcess.spawnSync(command, args, { encoding: "utf8" });

    if (spawn.error)
        throw spawn.error;

    spawn.stdout
        .toString()
        .replace(/\r\n/, "\n")
        .split("\n")
        .forEach(line => logCommand(line.trimRight()));

    spawn.stderr
        .toString()
        .replace(/\r\n/, "\n")
        .split("\n")
        .forEach(line => logUrgent(line.trimRight()));

    if (spawn.status)
        throw `${command} returned ${spawn.status}`;

    return spawn.stdout.toString();
}

//-------------------------------------------------------------------------------

function getTempPath() {
    const temp = tmp.dirSync();

    logDebug(`System tmp path: "${temp}"`);

    return temp;
}

//------------------------------------------------------------------------------

function dirExists(dir) {
    try {
        return fs.statSync(dir).isDirectory();
    }
    catch (e) {
        return false;
    }
}

//------------------------------------------------------------------------------

function getFolders(dir) {
    return fs.readdirSync(dir);
}

//------------------------------------------------------------------------------

function fileExists(file) {
    try {
        return fs.statSync(file).isFile();
    }
    catch (e) {
        return false;
    }
}

//------------------------------------------------------------------------------

function readFile(name) {
    return fs.readFileSync(name, "utf8");
}

//------------------------------------------------------------------------------

function readLines(name) {
    return readFile(name).split(/[\r\n|\r|\n]/);
}

//------------------------------------------------------------------------------

function JSONify(obj) {
    return JSON.stringify(obj, null, " ");
}

//------------------------------------------------------------------------------

function getRegistryValue(hive, key, name) {
    return new Promise((resolve, reject) => {
        try {
            const regKey = new WinReg({
                hive,
                key,
            });

            regKey.valueExists(name, (e, exists) => {
                if (e) {
                    reject(e);
                }

                if (exists) {
                    regKey.get(name, (err, result) => {
                        if (!err) {
                            resolve(result ? result.value : "");
                        } else {
                            reject(err);
                        }
                    });
                } else {
                    resolve("");
                }
            });
        } catch (error) {
            reject(error);
        }
    });
}

// #endregion

//==============================================================================
// #region ESP8266FS Specific code
//==============================================================================

function getPreferencesPath() {
    let dir = getVscodeConfigValue(ESP8266FS_PREFERENCES);

    if (!dir) {
        switch (getOS()) {
            case "win32":
                dir = path.join(process.env.LOCALAPPDATA, "Arduino15");
                break;

            case "linux":
                dir = path.join(process.env.HOME, ".arduino15");
                break;

            case "darwin":
                dir = path.join(process.env.HOME, "Library/Arduino15");
                break;
        }
    }

    if (!dir)
        throw `Can't find preferences path.`;

    dir = path.resolve(dir);

    if (!dirExists(dir))
        throw `Preferences path "${dir}" doesn't exist.`;

    logVerbose(`Preferences Path: "${dir}"`);
    return dir;
}

//-------------------------------------------------------------------------------

function getArduinoUserPath() {
    let dir = getVscodeConfigValue(ESP8266FS_ARDUINO_USER_PATH);

    if (!dir) {
        switch (getOS()) {
            case "win32":
                dir = path.join(process.env.USERPROFILE, "Documents", "Arduino");
                break;

            case "linux":
                dir = path.join(process.env.HOME, "Arduino");
                break;

            case "darwin":
                dir = path.join(process.env.HOME, "Documents", "Arduino");
                break;
        }
    }

    if (!dir)
        throw `Can't find arduino user path.`;

    dir = path.resolve(dir);

    if (!dirExists(dir))
        throw `Preferences path "${dir}" doesn't exist.`;

    logVerbose(`Arduino User Path: "${dir}"`);
    return dir;
}

//-------------------------------------------------------------------------------

function getDataFilesPath(arduinoJson) {
    let dir = getVscodeConfigValue(ESP8266FS_DATA_FILES) || "./data";

    if (dir.startsWith("."))
        dir = path.join(vscode.workspace.rootPath, dir);

    dir = path.resolve(dir);

    if (!dirExists(dir))
        throw `ESP8266 Data Files path "${dir}" not found.`;

    logVerbose(`ESP8266 Data Files path: "${dir}"`);

    return dir;
}

//-------------------------------------------------------------------------------

function getSpiffsImage() {
    let file = getVscodeConfigValue(ESP8266FS_SPIFFS_IMAGE)
        ||path.join(getTempPath(), "./spiffs.bin");

    if (file.startsWith("."))
        file = path.join(vscode.workspace.rootPath, file);

    file = path.resolve(file);

    logVerbose(`SPIFFS Image: "${file}"`);
    return file;
}

//-------------------------------------------------------------------------------

async function getArduinoPreferences(preferencesPath) {
    const preferences = {};

    const file = path.join(preferencesPath, "preferences.txt");
    logVerbose(`Reading preferences from "${file}"`);

    readLines(file)
        .forEach(line => {
            if (line.startsWith("#") || line.length == 0)
                return;

            const pair = line.split("=");

            logDebug(`  "${pair[0]}"="${pair[1]}"`);
            preferences[pair[0]] = pair[1];
        }
    );

    return preferences;
}

//-------------------------------------------------------------------------------

async function getArduinoJson() {
    var json = JSON.parse(readFile(path.join(vscode.workspace.rootPath, ARDUINO_CONFIG_FILE)));

        // Split the configuration settings into key/values

    if (json.configuration) {
        json.configuration.split(",").forEach(config => {
            let param = config.split("=");

            json[param[0]] = param[1];
        });
    }

    logDebug(`arduinoJson:`);
    JSONify(json).split("\n").map(line => logDebug(line));

    return json;
}
//-------------------------------------------------------------------------------

function _getTarget(arduinJson, preferences) {
    if (!arduinJson.board) {
        const target =
            {
                package: preferences["target_package"],
                architecture: preferences["target_platform"],
                board: preferences["board"]
            };

        return target;
    }

    const values = arduinJson.board.split(":");

    const target =
        {
            package: values[0],
            architecture: values[1],
            board: values[2]
        };

    return target;
}

//------------------------------------------------------------------------------

function getPreference(arduinoJson, preferences, index) {
    if (arduinoJson.hasOwnProperty(index))
        return arduinoJson[index];

    const value = preferences["custom_" + index];

    if (!value)
        throw `Can't determine ${index}.`;

    const match = value.match(/^(${target.board}|generic)_(\S+)/);

    return match ? match[2] : "";
}

//------------------------------------------------------------------------------

function getTarget(arduinoJson, preferences) {
    const target = _getTarget(arduinoJson, preferences);

    if (!["esp8266", "esp32"].includes(target.architecture))
        throw `Current Arduino package/architecture is not ESP8266 or ESP32.`;

    target.flashSize = getPreference(arduinoJson, preferences, "FlashSize");
    target.flashMode = getPreference(arduinoJson, preferences, "FlashMode");
    target.flashFreq = getPreference(arduinoJson, preferences, "FlashFreq");

    logDebug(`target:`);
    JSONify(target).split("\n").map(line => logDebug(line));

    return target;
}

//------------------------------------------------------------------------------

function getEspPackagePath(arduinoUserPath, preferencesPath, target) {
    switch (target.architecture) {
        case "esp8266": {
            const dir = path.join(preferencesPath, "packages", target.package, "hardware", target.architecture);

            if (!dirExists(dir))
                throw `ESP8266 has not been installed with the Arduino Board Manager.`;

            const folders = getFolders(dir);

            if (folders.length != 1)
                throw `There should only be one ESP8266 Package installed with the Arduino Board Manager.`;

            const esp8266Path = path.join(dir, folders[0]);
            logImportant(`Found ESP8266 packages: ${esp8266Path}`);

            return esp8266Path;
        }

        case "esp32": {
            const esp32Path = path.join(arduinoUserPath, "hardware", target.package, target.architecture);

            if (!dirExists(esp32Path))
                throw `ESP32 has not been installed correctly - see https://github.com/espressif/arduino-esp32.`;

            logImportant(`Found ESP32 packages: ${esp32Path}`);

            return esp32Path;
        }
    }
}

//------------------------------------------------------------------------------

function getSpiffsPartition(packagesPath, partition) {
    var data = {};

    readLines(path.join(packagesPath, "tools", "partitions", partition + ".csv"))
        .forEach(line => {
            const values = line.split(",");

            data[values[0]] = {
                "type":    (values[1] || "").trim(),
                "subType": (values[2] || "").trim(),
                "offset":  (values[3] || "").trim(),
                "size":    (values[4] || "").trim(),
                "flags":   (values[5] || "").trim()
            };
        }
    );

    return data;
}

//------------------------------------------------------------------------------

function getSpiffsOptions(packagesPath, target, arduinoJson, preferences) {
    const spiffsOptions = {};

    readLines(path.join(packagesPath, "boards.txt"))
        .forEach(line => {
            const match = line.match(`${target.board}\\.(?:build|upload)\\.(\\S+)=(\\S+)`)
                       || line.match(`${target.board}\\.menu\\.FlashSize\\.${target.flashSize}\\.(?:build|upload)\\.(\\S+)=(\\S+)`)
                       || line.match(`${target.board}\\.menu\\.PartitionScheme\\.${arduinoJson.PartitionScheme}\\.(?:build|upload)\\.(\\S+)=(\\S+)`);

            if (match)
                spiffsOptions[match[1]] = match[2];
        }
    );

    switch (target.architecture) {
        case "esp8266": {
                if (!spiffsOptions.spiffs_start)
                    throw `Missing "spiffs_start" definition: target = ${target.architecture}, config = ${target.memoryConfig}.`;

                if (!spiffsOptions.spiffs_end)
                    throw `Missing "spiffs_end" definition: target = ${target.architecture}, config = ${target.memoryConfig}.`;

                spiffsOptions.dataSize = (stringToInt(spiffsOptions.spiffs_end) - stringToInt(spiffsOptions.spiffs_start)).toString();
            }
            break;

        case "esp32": {
                if (!spiffsOptions.partitions)
                    throw `Missing "partitions" definition: target = ${target}, config = ${arduinoJson.PartitionScheme}.`;

                const partition = getSpiffsPartition(packagesPath, spiffsOptions.partitions);

                spiffsOptions.spiffs_start = partition.spiffs.offset;
                spiffsOptions.dataSize = partition.spiffs.size;
            }
            break;
    }

    spiffsOptions.flashMode = preferences.flash_mode;
    spiffsOptions.flashFreq = preferences.flash_freq;
    spiffsOptions.flashSize = "0x" + toHex(stringToInt(spiffsOptions.spiffs_start) + stringToInt(spiffsOptions.dataSize));

    if (arduinoJson.UploadSpeed)
        spiffsOptions.speed = arduinoJson.UploadSpeed;

    if (arduinoJson.ResetMethod)
        spiffsOptions.resetmethod = arduinoJson.ResetMethod;

    logDebug(`spiffs:`);
    JSONify(spiffsOptions).split("\n").map(line => logDebug(line));

    return spiffsOptions;
}

//------------------------------------------------------------------------------

function getEspToolsPath(arduinoUserPath, preferencesPath, target) {
    const dir = target.architecture == "esp8266"
                ? path.resolve(path.join(preferencesPath, "packages", target.architecture, "tools"))
                : path.resolve(path.join(arduinoUserPath, "hardware", target.package, target.architecture, "tools"));

    if (!dirExists(dir))
        throw `Can't find tools path.`;

    logVerbose(`Tools Path: "${dir}"`);
    return dir;
}

//------------------------------------------------------------------------------

function getPythonExecutable() {
    const python = getVscodeConfigValue(PYTHON_PYTHONPATH) || "python";

    logVerbose(`Python Executable: "${python}"`);
    return python;
}

//------------------------------------------------------------------------------

function getEspotaPy(packagePath) {
    const file = getVscodeConfigValue(ESP8266FS_ESPOTA_PY) || path.join(packagePath, "tools", "espota.py");

    if (!fileExists(file))
        throw `Can't find ${file}.`;

    logVerbose(`espota.py: ${CYAN}${file}`);
    return file;
}

//------------------------------------------------------------------------------

function getPort(arduinoJson, preferences) {
    let port = arduinoJson.port || preferences["serial.port"];

    logVerbose(`Output Port: ${port}`);
    return port;
}

//------------------------------------------------------------------------------

function isIP(port) {
    return port.match(/^(\d+)\.(\d+).(\d+).(\d+)(:\d+)?$/);
}

// #endregion

//==============================================================================
// #region MKSPIFFS

function getMkSpiffs(target, espToolsPath) {
    const configFile = getVscodeConfigValue(ESP8266FS_MKSPIFFS_EXECUTABLE);

    if (configFile) {
        if (!fileExists(configFile))
            throw `Can't locate ${configFile}.`;

        logVerbose(`mkspiffs: ${CYAN}${configFile}`);
        logImportant(`Found "mkspiffs" via VSCode Configuration`);

        return configFile;
    }

    switch (target.architecture) {
        case "esp8266": {
            const folders = getFolders(path.join(espToolsPath, "mkspiffs"));

            if (folders.length != 1)
                throw `"${target.architecture}" not installed correctly through Arduino Board Manager`;

            const mkspiffs = path.join(espToolsPath, "mkspiffs", folders[0], program("mkspiffs"));

            if (!fileExists(mkspiffs))
                throw `"Can't locate "${mkspiffs}"`;

            return mkspiffs;
        }

        case "esp32": {
            const mkspiffs = path.join(espToolsPath, "mkspiffs", program("mkspiffs"));

            if (!fileExists(mkspiffs))
                throw `"Can't locate "${mkspiffs}"`;

            return mkspiffs;
        }
    }
}

//------------------------------------------------------------------------------

function makeMkspiffsArgs(args) {
    const allFiles = getVscodeConfigValue(ESP8266FS_MKSPIFFS_ALL_FILES);

    if (allFiles)
        args.unshift("--all-files", allFiles);

    const debug = getVscodeConfigValue(ESP8266FS_MKSPIFFS_DEBUG_LEVEL);

    if (debug)
        args.unshift("--debug", debug);

    return args;
}

//------------------------------------------------------------------------------

function packSpiffs(mkspiffs, dataPath, spiffsOptions, spiffsImage) {
    log(`--- Packing SPIFFS file ---`);

    const dataSize = spiffsOptions.dataSize;
    const dataSizeInK = (dataSize >> 10) + 1;
    const spiPage = stringToInt(spiffsOptions.spiffs_pagesize || "256");
    const spiBlock = stringToInt(spiffsOptions.spiffs_blocksize || "4096");

    logImportant(`SPIFFS Creating Image... (${spiffsImage})`);
    logSpiffs(`program: ${mkspiffs}`);
    logSpiffs(`data   : ${dataPath}`);
    logSpiffs(`size   : ${dataSizeInK}K`);
    logSpiffs(`page   : ${spiPage}`);
    logSpiffs(`block  : ${spiBlock}`);

    runCommand(
        makeOsPath(mkspiffs),
        makeMkspiffsArgs([
            "--create", makeOsPath(dataPath),
            "--size", dataSize,
            "--page", spiPage,
            "--block", spiBlock,
            makeOsPath(spiffsImage)
        ])
    );
}

//------------------------------------------------------------------------------

function unpackSpiffs(mkspiffs, dataPath, spiffsOptions, spiffsImage) {
    log(`--- Unpacking SPIFFS file ---`);

    const dataSize = spiffsOptions.dataSize;
    const dataSizeInK = (dataSize >> 10) + 1;
    const spiPage = stringToInt(spiffsOptions.spiffs_pagesize || "256");
    const spiBlock = stringToInt(spiffsOptions.spiffs_blocksize || "4096");

    logImportant(`SPIFFS Unpacking Image... (${spiffsImage})`);
    logSpiffs(`program: ${mkspiffs}`);
    logSpiffs(`data   : ${dataPath}`);
    logSpiffs(`size   : ${dataSizeInK}K`);
    logSpiffs(`page   : ${spiPage}`);
    logSpiffs(`block  : ${spiBlock}`);

    runCommand(
        makeOsPath(mkspiffs),
        makeMkspiffsArgs([
            "--unpack", makeOsPath(dataPath),
            "--size", dataSize,
            "--page", spiPage,
            "--block", spiBlock,
            makeOsPath(spiffsImage)
        ])
    );
}

//------------------------------------------------------------------------------

function listSpiffs(mkspiffs, spiffsOptions, spiffsImage) {
    log(`--- List SPIFFS file ---`);

    const spiPage = stringToInt(spiffsOptions.spiffs_pagesize || "256");
    const spiBlock = stringToInt(spiffsOptions.spiffs_blocksize || "4096");

    logImportant(`SPIFFS List Files... (${spiffsImage})`);
    logSpiffs(`program: ${mkspiffs}`);
    logSpiffs(`page   : ${spiPage}`);
    logSpiffs(`block  : ${spiBlock}`);

    runCommand(
        makeOsPath(mkspiffs),
        makeMkspiffsArgs([
            "--list",
            "--page", spiPage,
            "--block", spiBlock,
            makeOsPath(spiffsImage)
        ])
    );
}

//------------------------------------------------------------------------------

function visualizeSpiffs(mkspiffs, spiffsOptions, spiffsImage) {
    log(`--- Visualize SPIFFS file ---`);

    const spiPage = stringToInt(spiffsOptions.spiffs_pagesize || "256");
    const spiBlock = stringToInt(spiffsOptions.spiffs_blocksize || "4096");

    logImportant(`SPIFFS Visualize Files... (${spiffsImage})`);
    logSpiffs(`program: ${mkspiffs}`);
    logSpiffs(`page   : ${spiPage}`);
    logSpiffs(`block  : ${spiBlock}`);

    runCommand(
        makeOsPath(mkspiffs),
        makeMkspiffsArgs([
            "--visualize",
            "--page", spiPage,
            "--block", spiBlock,
            makeOsPath(spiffsImage)
        ])
    );
}

// #endregion

//==============================================================================
// #region ESPTOOL

function getEspTool(target, espToolsPath) {
    const configFile = getVscodeConfigValue(ESP8266FS_ESPTOOL_EXECUTABLE);

    if (configFile) {
        if (!fileExists(configFile))
            throw `Can't locate ${configFile}.`;

        logVerbose(`esptool: ${CYAN}${configFile}`);
        logImportant(`Found "esptool" via VSCode Configuration`);

        return configFile;
    }

    switch (target.architecture) {
        case "esp8266": {
            const folders = getFolders(path.join(espToolsPath, "esptool"));

            if (folders.length != 1)
                throw `"${target.architecture}" not installed correctly through Arduino Board Manager`;

            const version = folders[0];

            const esptool = path.join(espToolsPath, "esptool", version, program("esptool"));

            if (!fileExists(esptool))
                throw `"Can't locate "${esptool}"`;

            logVerbose(`esptool (${version}): ${CYAN}${esptool}`);

            return esptool;
        }

        case "esp32": {
            const esptoolPy = path.join(espToolsPath, program("esptool.py"));

            if (!fileExists(esptoolPy))
                throw `"Can't locate "${esptoolPy}"`;

            logVerbose(`esptool: ${CYAN}${esptoolPy}`);

            return esptoolPy;
        }
    }
}

//------------------------------------------------------------------------------

// -ca <address>
// -cd <resetMethod>
// -cp <port>
// -cb <speed>
// -vvv

function _uploadSpiffsEspTool(esptool, commPort, spiffsImage, spiffsOptions) {
    log(`--- Uploading SPIFFS file with esptool[.exe] ---`);

    const uploadAddress = `0x` + toHex(stringToInt(spiffsOptions.spiffs_start), 6);
    const uploadSpeed = stringToInt(spiffsOptions.speed);
    const resetMethod = spiffsOptions.resetmethod;

    logImportant(`SPIFFS Uploading Image... (${spiffsImage})`);
    logSpiffs(`program: ${esptool}`);
    logSpiffs(`address: ${uploadAddress}`);
    logSpiffs(`reset  : ${resetMethod}`);
    logSpiffs(`port   : ${commPort}`);
    logSpiffs(`speed  : ${uploadSpeed}`);

    let args = [
        "-ca", uploadAddress,          // Address in flash.
        "-cd", resetMethod,            // Board reset method: "none", "ck", "nodemcu", or "wifio".
        "-cp", commPort,               // Serial Port (Default Linux: /dev/ttyUSB0, Windows: COM1, OSx: /dev/tty.usbserial).
        "-cb", uploadSpeed,            // Baud rate (Default: 115200).
        "-cf", makeOsPath(spiffsImage) // SPIFFS File
    ];

    const verbosity = getVscodeConfigValue(ESP8266FS_ESPTOOL_VERBOSITY);

    if (verbosity)
        args.unshift(`-${verbosity}`);

    runCommand(makeOsPath(esptool), args);
}

//------------------------------------------------------------------------------

// --chip auto,esp32,esp8266
// --baud <rate>
// --port <port>
// --before default_reset,no_reset
// --after hard_reset,soft_reset,no_reset
// --no_stub
// --trace
//  write_flash
// --compress
// --flash_mode <mode>
// --flash_freq <freq>
// --flash_size <size>
// --spi_connection <spi>
// --verify

function _uploadSpiffsEspToolPy(esptool, commPort, spiffsImage, spiffsOptions, target) {
    log(`--- Uploading SPIFFS file with esptool.py ---`);

    const python = getPythonExecutable();

    const uploadAddress = `0x` + toHex(stringToInt(spiffsOptions.spiffs_start), 6);
    const uploadSpeed = stringToInt(spiffsOptions.speed);
    const resetMethod = spiffsOptions.resetmethod;

    const before = getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_BEFORE) || "default_reset";
    const after = getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_AFTER) || "hard_reset";

    const flashMode = target.flashMode;
    const flashFreq = target.flashFreq;
    const flashSize = target.flashSize || "detect";

    logImportant(`SPIFFS Uploading Image... (${spiffsImage})`);
    logSpiffs(`Python   : ${python}`);
    logSpiffs(`EspTool  : ${esptool}`);
    logSpiffs(`address  : ${uploadAddress}`);
    logSpiffs(`port     : ${commPort}`);
    logSpiffs(`speed    : ${uploadSpeed}`);
    logSpiffs(`before   : ${before}`);
    logSpiffs(`after    : ${after}`);
    logSpiffs(`flashMode: ${flashMode}`);
    logSpiffs(`flashFreq: ${flashFreq}`);
    logSpiffs(`flashSize: ${flashSize}`);

    const spi = getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_SPI) || "";
    if (spi)
        logSpiffs(`SPI      : ${spi}`);

    let compress = getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_COMPRESS);
    if (compress) {
        logSpiffs(`compress : ${compress}`);
        compress = compress == "true";
    } else
        compress = false;

    let args = [
        esptool,
        "--chip", target.architecture,
        "--baud", uploadSpeed,
        "--port", commPort,
        "--before", before,
        "--after", after
    ];

    if (getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_NO_STUB) == "true")
        args.push("--no-stub");

    if (getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_TRACE) == "true")
        args.push("--trace");

    args.push("write_flash");

    if (compress)
        args.push("--compress");

    args.push(
        "--flash_mode", flashMode,
        "--flash_freq", flashFreq,
        "--flash_size", flashSize
    );

    if (spi)
        args.push("--spi-connection", spi);

    if (getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_VERIFY) == "true")
        args.push("--verify");

    args.push(uploadAddress, makeOsPath(spiffsImage));

    runCommand(makeOsPath(python), args);
}

//------------------------------------------------------------------------------

// --chip auto,esp32,esp8266
// --baud <rate>
// --port <port>
// --before default_reset,no_reset
// --after hard_reset,soft_reset,no_reset
// --no_stub
// --trace
//  read_flash
// --flash_mode <mode>
// --flash_freq <freq>
// --flash_size <size>
// --spi_connection <spi>
// --verify

function _downloadSpiffsEspToolPy(esptool, commPort, spiffsImage, spiffsOptions, target) {
    log(`--- Downloading SPIFFS file with esptool.py ---`);

    const python = getPythonExecutable();

    const downloadAddress = `0x` + toHex(stringToInt(spiffsOptions.spiffs_start), 6);
    const uploadSpeed = stringToInt(spiffsOptions.speed);
    const resetMethod = spiffsOptions.resetmethod;

    const before = getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_BEFORE) || "default_reset";
    const after = getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_AFTER) || "hard_reset";

    const flashMode = target.flashMode;
    const flashFreq = target.flashFreq;
    const flashSize = target.flashSize || "detect";

    logImportant(`SPIFFS Uploading Image... (${spiffsImage})`);
    logSpiffs(`Python   : ${python}`);
    logSpiffs(`EspTool  : ${esptool}`);
    logSpiffs(`address  : ${downloadAddress}`);
    logSpiffs(`port     : ${commPort}`);
    logSpiffs(`speed    : ${uploadSpeed}`);
    logSpiffs(`before   : ${before}`);
    logSpiffs(`after    : ${after}`);
    logSpiffs(`flashMode: ${flashMode}`);
    logSpiffs(`flashFreq: ${flashFreq}`);
    logSpiffs(`flashSize: ${flashSize}`);

    const spi = getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_SPI) || "";
    if (spi)
        logSpiffs(`SPI      : ${spi}`);

    let args = [
        esptool,
        "--chip", target.architecture,
        "--baud", uploadSpeed,
        "--port", commPort,
        "--before", before,
        "--after", after
    ];

    if (getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_NO_STUB) == "true")
        args.push("--no-stub");

    if (getVscodeConfigValue(ESP8266FS_ESPTOOL_PY_TRACE) == "true")
        args.push("--trace");

    args.push("write_flash");

    args.push(
        "--flash_mode", flashMode,
        "--flash_freq", flashFreq,
        "--flash_size", flashSize
    );

    if (spi)
        args.push("--spi-connection", spi);

    args.push(downloadAddress, makeOsPath(spiffsImage));

    runCommand(makeOsPath(python), args);
}
//------------------------------------------------------------------------------

function uploadSpiffsEspTool(esptool, commPort, spiffsImage, spiffsOptions, target) {
    if (esptool.match(/\.py$/))
        _uploadSpiffsEspToolPy(esptool, commPort, spiffsImage, spiffsOptions, target);
    else
        _uploadSpiffsEspTool(esptool, commPort, spiffsImage, spiffsOptions);
}

//------------------------------------------------------------------------------

function downloadSpiffsEspTool(esptool, commPort, spiffsImage, spiffsOptions, target) {
    if (!esptool.match(/\.py$/))
        throw `Downloading only available if using "esptool.py"`;

    _downloadSpiffsEspToolPy(esptool, commPort, spiffsImage, spiffsOptions, target);
}

// #endregion

//==============================================================================
// #region ESPOTA.PY

// --ip <address>
// --port <port>         default: 8266
// --host_ip <address>   default: 0.0.0.0
// --host_port <port>    default: random(10000, 60000)
// --auth <password>
// --spiffs
// --debug
// --file <image>

function uploadSpiffsOta(espota, ip, spiffsImage) {
    log(`--- Uploading SPIFFS file via OTA ---`);

    let port = 8266;

    if (ip.indexOf(":") != -1)
        [ ip, port ] = ip.split(":");

    port = getVscodeConfigValue(ESP8266FS_ESPOTA_ESP_PORT) || port;

    let host = getVscodeConfigValue(ESP8266FS_ESPOTA_HOST_IP);
    let host_port = "";

    if (host.indexOf(":") != -1)
        [ host, host_port ] = host.split(":");

    host_port = getVscodeConfigValue(ESP8266FS_ESPOTA_HOST_PORT) || host_port;
    const python = program(getPythonExecutable());

    logImportant(`SPIFFS Uploading Image... (${spiffsImage})`);
    logSpiffs(`Python   : ${python}`);
    logSpiffs(`EspOTA   : ${espota}`);
    logSpiffs(`IP       : ${ip}`);
    logSpiffs(`Port     : ${port}`);
    logSpiffs(`Host IP  : ${host}`);
    logSpiffs(`Host Port: ${host_port}`);

    let args = [
        makeOsPath(espota),               // Python code
        "--ip",     ip                    // IP address
    ];

    if (port)
        args.push("--port", port);

    if (host)
        args.push("--host_ip", host);

    if (host_port)
        args.push("--host_port", host_port);

    let auth = getVscodeConfigValue(ESP8266FS_ESPOTA_AUTH);

    if (auth)
        args.push("--auth", auth);

    if (getVscodeConfigValue(ESP8266FS_ESPOTA_DEBUG))
        args.push("--debug");

    args.push(
        "--spiffs",                       // Sending SPIFFS - do not FLASH!
        "--file",   makeOsPath(spiffsImage)
    );

    runCommand(makeOsPath(python), args);
}

// #endregion

//==============================================================================
// #region VSCode Command Handlers

async function _executeSpiffs(command) {
    const arduinoJson = await getArduinoJson();
    const preferencesPath = await getPreferencesPath();
    const preferences = await getArduinoPreferences(preferencesPath);

    const target = getTarget(arduinoJson, preferences);

    const dataPath = getDataFilesPath(arduinoJson);
    const spiffsImage = getSpiffsImage();

    const arduinoUserPath = getArduinoUserPath();
    const espPackagePath = getEspPackagePath(arduinoUserPath, preferencesPath, target);
    const espToolsPath = getEspToolsPath(arduinoUserPath, preferencesPath, target);

    const spiffsOptions = getSpiffsOptions(espPackagePath, target, arduinoJson, preferences);

    const port = getPort(arduinoJson, preferences);

    const mkspiffs = getMkSpiffs(target, espToolsPath);

        // --- Ready to get down to business ---

    switch (command) {
        case "upload": {
            if (isIP(port))
                uploadSpiffsOta(getEspotaPy(espPackagePath), port, spiffsImage);
            else
                uploadSpiffsEspTool(getEspTool(target, espToolsPath), port, spiffsImage, spiffsOptions, target);

            break;
        }

        case "download": {
            if (isIP(port))
                throw `No OTA support for "download"`;

            downloadSpiffsEspTool(getEspTool(target, espToolsPath), port, spiffsImage, spiffsOptions, target);

            break;
        }

        case "pack":
            packSpiffs(mkspiffs, dataPath, spiffsOptions, spiffsImage);
            break;

        case "unpack":
            unpackSpiffs(mkspiffs, dataPath, spiffsOptions, spiffsImage);
            break;

        case "list":
            listSpiffs(mkspiffs, spiffsOptions, spiffsImage);
            break;

        case "visualize":
            visualizeSpiffs(mkspiffs, spiffsOptions, spiffsImage);
            break;
    }
 }

//------------------------------------------------------------------------------

var locked = null;

async function executeSpiffs(command) {
    if (locked) {
        showErrorMessage(`ESP8266FS already running "${locked}"!`);
        return;
    }

    logLevel = getVscodeConfigValue(ESP8266FS_LOGLEVEL) || logLevel;

    logAnnounce(`ESP8266 SPIFFS interface started: "${command}".`);
    locked = command;

    try {
        await _executeSpiffs(command);
        showInformationMessage(`ESP266FS "${command}" completed!`);
    } catch (error) {
        logUrgent(error);
        showErrorMessage(error);
        locked = null;
    }

    logAnnounce(`ESP8266 SPIFFS interface finished.`);
    locked = null;
}

//------------------------------------------------------------------------------

async function activate(context) {
    outputChannel = vscode.window.createOutputChannel("ESP8266FS");
    logLevel = getVscodeConfigValue(ESP8266FS_LOGLEVEL) || "normal";
    logVerbose(`ESP8266FS is now active!`);

    context.subscriptions.push(vscode.commands.registerCommand('esp8266fs.uploadSpiffs',    () => { executeSpiffs("upload"); }));
    context.subscriptions.push(vscode.commands.registerCommand('esp8266fs.downloadSpiffs',  () => { executeSpiffs("download"); }));
    context.subscriptions.push(vscode.commands.registerCommand('esp8266fs.packSpiffs',      () => { executeSpiffs("pack"); }));
    context.subscriptions.push(vscode.commands.registerCommand('esp8266fs.unpackSpiffs',    () => { executeSpiffs("unpack"); }));
    context.subscriptions.push(vscode.commands.registerCommand('esp8266fs.listSpiffs',      () => { executeSpiffs("list"); }));
    context.subscriptions.push(vscode.commands.registerCommand('esp8266fs.visualizeSpiffs', () => { executeSpiffs("visualize"); }));
}

exports.activate = activate;

//------------------------------------------------------------------------------

function deactivate() {}

exports.deactivate = (() => {});

// #endregion