Skip to content

A Hardware Hacking Tool with Web-Based CLI That Speaks Every Protocol

17.7 KB
Raw Blame
#include "Controllers/UtilityController.h"

/*
Constructor
*/
UtilityController::UtilityController(
    ITerminalView& terminalView,
    IDeviceView& deviceView,
    IInput& terminalInput,
    PinService& pinService,
    UserInputManager& userInputManager,
    PinAnalyzeManager& pinAnalyzeManager,
    ArgTransformer& argTransformer,
    SysInfoShell& sysInfoShell,
    GuideShell& guideShell,
    HelpShell& helpShell,
    ProfileShell& profileShell
)
    : terminalView(terminalView),
      deviceView(deviceView),
      terminalInput(terminalInput),
      pinService(pinService),
      userInputManager(userInputManager),
      pinAnalyzeManager(pinAnalyzeManager),
      argTransformer(argTransformer),
      sysInfoShell(sysInfoShell),
      guideShell(guideShell),
      helpShell(helpShell),
      profileShell(profileShell)
{}

/*
Entry point for command
*/
void UtilityController::handleCommand(const TerminalCommand& cmd) {
    if (cmd.getRoot() == "help" || cmd.getRoot() == "h" || cmd.getRoot() == "?") handleHelp();
    else if (cmd.getRoot() == "P")                                               handleEnablePullups();
    else if (cmd.getRoot() == "p")                                               handleDisablePullups();
    else if (cmd.getRoot() == "logic")                                           handleLogicAnalyzer(cmd);
    else if (cmd.getRoot() == "analogic")                                        handleAnalogic(cmd);
    else if (cmd.getRoot() == "system" || cmd.getRoot() == "sys")                handleSystem();
    else if (cmd.getRoot() == "guide" || cmd.getRoot() == "man")                 handleGuide();
    else if (cmd.getRoot() == "hex" || cmd.getRoot() == "dec")                   handleHex(cmd);
    else if (cmd.getRoot() == "wizard")                                          handleWizard(cmd);
    else if (cmd.getRoot() == "profile")                                         handleProfile();
    else {
        helpShell.run(state.getCurrentMode(), false);
    }
}

/*
Mode Change
*/
ModeEnum UtilityController::handleModeChangeCommand(const TerminalCommand& cmd) {
    if (cmd.getRoot() != "mode" && cmd.getRoot() != "m") {
        terminalView.println("Invalid command for mode change.");
        return ModeEnum::None;
    }

    if (!cmd.getSubcommand().empty()) {
        ModeEnum newMode = ModeEnumMapper::fromString(cmd.getSubcommand());
        if (newMode != ModeEnum::None) {
            terminalView.println("Mode changed to " + ModeEnumMapper::toString(newMode));
            terminalView.println(""); 
            return newMode;
        } else {
            terminalView.println("Unknown mode: " + cmd.getSubcommand());
            return ModeEnum::None;
        }
    }

    return handleModeSelect();
}

/*
Mode Select
*/
ModeEnum UtilityController::handleModeSelect() {
    terminalView.println("");
    terminalView.println("Select mode:");
    std::vector<ModeEnum> modes;

    for (int i = 0; i < static_cast<int>(ModeEnum::COUNT); ++i) {
        ModeEnum mode = static_cast<ModeEnum>(i);
        std::string name = ModeEnumMapper::toString(mode);
        if (!name.empty()) {
            modes.push_back(mode);
            terminalView.println("  " + std::to_string(modes.size()) + ". " + name);
        }
    }

    terminalView.println("");
    terminalView.print("Mode Number > ");
    auto modeNumber = userInputManager.readModeNumber();

    if (modeNumber == -1) {
        terminalView.println("");
        terminalView.println("");
        terminalView.println("Invalid input.");
        return ModeEnum::None;
    } else if (modeNumber >= 1 && modeNumber <= modes.size()) {
        ModeEnum selected = modes[modeNumber - 1];
        if (static_cast<int>(selected) > 9) {
            terminalView.println(""); // Hack to render correctly on web terminal
        }
        terminalView.println("");
        terminalView.println("Mode changed to " + ModeEnumMapper::toString(selected));
        terminalView.println("");
        return selected;
    } else {
        terminalView.println("");
        terminalView.println("Invalid mode number.");
        terminalView.println("");
        return ModeEnum::None;
    }
}

/*
Pullup: p
*/
void UtilityController::handleDisablePullups() {
    auto mode = state.getCurrentMode();
    switch (mode) {
        case ModeEnum::SPI:
            pinService.setInput(state.getSpiMISOPin());
            terminalView.println("SPI: Pull-ups disabled on MISO");
            break;

        case ModeEnum::I2C:
            pinService.setInput(state.getI2cSdaPin());
            pinService.setInput(state.getI2cSclPin());
            terminalView.println("I2C: Pull-ups disabled on SDA, SCL.");
            break;

        case ModeEnum::OneWire:
            pinService.setInput(state.getOneWirePin());
            terminalView.println("1-Wire: Pull-up disabled on DQ.");
            break;

        case ModeEnum::UART:
            pinService.setInput(state.getUartRxPin());
            terminalView.println("UART: Pull-ups disabled on RX.");
            break;

        case ModeEnum::HDUART:
            pinService.setInput(state.getHdUartPin());
            terminalView.println("HDUART: Pull-up disabled on IO pin.");
            break;

        case ModeEnum::TwoWire:
            pinService.setInput(state.getTwoWireIoPin());
            terminalView.println("2-WIRE: Pull-up disabled on DATA pin.");
            break;

        case ModeEnum::JTAG:
            for (auto pin : state.getJtagScanPins()) {
                pinService.setInput(pin);
            }
            terminalView.println("JTAG: Pull-ups disabled on all scan pins.");
            break;

        default:
            terminalView.println("Pull-ups not applicable for this mode.");
            break;
    }
}

/*
Pullup P
*/
void UtilityController::handleEnablePullups() {
    auto mode = state.getCurrentMode();
    switch (mode) {
        case ModeEnum::SPI:
            pinService.setInput(state.getSpiMISOPin());
            pinService.setInputPullup(state.getSpiMISOPin());
            terminalView.println("SPI: Pull-up enabled on MISO.");
            break;

        case ModeEnum::I2C:
            pinService.setInputPullup(state.getI2cSdaPin());
            pinService.setInputPullup(state.getI2cSclPin());
            terminalView.println("I2C: Pull-ups enabled on SDA, SCL.");
            break;

        case ModeEnum::OneWire:
            pinService.setInputPullup(state.getOneWirePin());
            terminalView.println("1-Wire: Pull-up enabled on DQ.");
            break;

        case ModeEnum::UART:
            pinService.setInputPullup(state.getUartRxPin());
            terminalView.println("UART: Pull-up enabled on RX.");
            break;

        case ModeEnum::HDUART:
            pinService.setInputPullup(state.getHdUartPin());
            terminalView.println("HDUART: Pull-up enabled on IO pin.");
            break;

        case ModeEnum::TwoWire:
            pinService.setInputPullup(state.getTwoWireIoPin());
            terminalView.println("2-WIRE: Pull-up enabled on DATA pin.");
            break;

        case ModeEnum::JTAG:
            for (auto pin : state.getJtagScanPins()) {
                pinService.setInputPullup(pin);
            }
            terminalView.println("JTAG: Pull-ups enabled on all scan pins.");
            break;

        default:
            terminalView.println("Pull-ups not applicable for this mode.");
            break;
    }
}

/*
Logic
*/
void UtilityController::handleLogicAnalyzer(const TerminalCommand& cmd) {

    uint16_t tDelay = 500;
    uint16_t inc = 100; // tDelay will be decremented/incremented by inc
    uint8_t step = 1; // step of the trace display kind of a zoom

    if (cmd.getSubcommand().empty() || !argTransformer.isValidNumber(cmd.getSubcommand())) {
        terminalView.println("Usage: logic <pin>");
        return;
    }

    // Verify protected pin
    uint8_t pin = argTransformer.toUint8(cmd.getSubcommand());
    /*
    auto forbidden = state.getProtectedPins();
    if (std::find(forbidden.begin(), forbidden.end(), pin) != forbidden.end()) {
        terminalView.println("Logic Analyzer: This pin is protected or reserved.");
        return;
    }
*/
    if (state.isPinProtected(pin)) {
        terminalView.println("Logic Analyzer: This pin is protected or reserved.");
        return;
    }
    terminalView.println("\nLogic Analyzer: Monitoring pin " + std::to_string(pin) + "... Press [ENTER] to stop.");
    terminalView.println("Displaying waveform on the ESP32 screen...\n");


    pinService.setInput(pin);
    std::vector<uint8_t> buffer;
    buffer.reserve(320); // 320 samples

    unsigned long lastCheck = millis();
    deviceView.clear();
    deviceView.topBar("Logic Analyzer", false, false);

    while (true) {
        // Enter press
        if (millis() - lastCheck > 10) {
            lastCheck = millis();
            char c = terminalInput.readChar();
            if (c == '\r' || c == '\n') {
                // fdufnews 2025/10/24 added to restore cursor position when leaving
                if (state.getTerminalMode() == TerminalTypeEnum::Serial)
                    terminalView.print("\n\n\n\n\r"); // 4 lines down to place cursor just under the logic trace
                terminalView.println("Logic Analyzer: Stopped by user.");
                break;
            }
            if (c == 's'){
                if (tDelay > inc){
                    tDelay -= inc;
                    terminalView.println("delay : " + std::to_string(tDelay) + "\n");
                }
            };
            if (c == 'S'){
                if (tDelay < 10000){
                    tDelay += inc;
                    terminalView.println("delay : " + std::to_string(tDelay) + "\n");
                }
            };
            if (c == 'z'){
                if (step > 1){
                    step--;
                    terminalView.println("step : " + std::to_string(step) + "\n");
                }
            };
            if (c == 'Z'){
                if (step < 4){
                    step++;
                    terminalView.println("step : " + std::to_string(step) + "\n");
                }
            };
        }

        // Draw
        if (buffer.size() >= 320) {
            buffer.resize(320);
            deviceView.drawLogicTrace(pin, buffer, step);

            // The poor man's drawLogicTrace() on terminal
            // draws a 132 samples sub part of the buffer to speed up the things
            if (state.getTerminalMode() == TerminalTypeEnum::Serial){
                terminalView.println("");
                uint8_t pos = 0;
                for(size_t i = 0; i < 132; i++, pos++){
                     terminalView.print(buffer[i]?"-":"_");
                }
                terminalView.print("\r\x1b[A");  // Up 1 line to put cursor at the correct place for the next draw
            }
            buffer.clear();
        }

        buffer.push_back(pinService.read(pin));
        delayMicroseconds(tDelay);
    }
}

/*
Analogic
*/
void UtilityController::handleAnalogic(const TerminalCommand& cmd) {
    uint16_t tDelay = 500;
    uint16_t inc = 100; // tDelay will be decremented/incremented by inc
    uint8_t step = 1; // step of the trace display kind of a zoom

    if (cmd.getSubcommand().empty() || !argTransformer.isValidNumber(cmd.getSubcommand())) {
        terminalView.println("Usage: analogic <pin>");
        return;
    }

    // Verify protected pin
    uint8_t pin = argTransformer.toUint8(cmd.getSubcommand());
    if (state.isPinProtected(pin)) {
        terminalView.println("Analogic: This pin is protected or reserved.");
        return;
    }
    if (!state.isPinAnalog(pin)){
        terminalView.println("Analogic: This pin is not an analog one");
        return;
    };

    terminalView.println("\nAnalogic: Monitoring pin " + std::to_string(pin) + "... Press [ENTER] to stop.");
    terminalView.println("Displaying waveform on the ESP32 screen...\n");


    pinService.setInput(pin);
    std::vector<uint8_t> buffer;
    buffer.reserve(320); // 320 samples

    unsigned long lastCheck = millis();
    deviceView.clear();
    deviceView.topBar("Analog plotter", false, false);
    int count = 0;
    while (true) {
        // Enter press
        if (millis() - lastCheck > 10) {
            lastCheck = millis();
            char c = terminalInput.readChar();
            if (c == '\r' || c == '\n') {
                terminalView.println("\nAnalogic: Stopped by user.");
                break;
            }
            if (c == 's'){
                if (tDelay > inc){
                    tDelay -= inc;
                    terminalView.println("\ndelay : " + std::to_string(tDelay) + "\n");
                }
            };
            if (c == 'S'){
                if (tDelay < 10000){
                    tDelay += inc;
                    terminalView.println("\ndelay : " + std::to_string(tDelay) + "\n");
                }
            };
            if (c == 'z'){
                if (step > 1){
                    step--;
                    terminalView.println("\nstep : " + std::to_string(step) + "\n");
                }
            };
            if (c == 'Z'){
                if (step < 4){
                    step++;
                    terminalView.println("\nstep : " + std::to_string(step) + "\n");
                }
            };
            count++;
            if ((count > 50) && (state.getTerminalMode() != TerminalTypeEnum::Standalone)){
                int raw = pinService.readAnalog(pin);
                float voltage = (raw / 4095.0f) * 3.3f;

                std::ostringstream oss;
                oss << "   Analog pin " << static_cast<int>(pin)
                    << ": " << raw
                    << " (" << voltage << " V)";
                terminalView.println(oss.str());
                count = 0;
            }
        }

        // Draw
        if (buffer.size() >= 320) {
            buffer.resize(320);
            deviceView.drawAnalogicTrace(pin, buffer, step);
            buffer.clear();
        }

        buffer.push_back(pinService.readAnalog(pin) >> 4); // convert the readAnalog() value to a uint8_t (4096 ==> 256)
        delayMicroseconds(tDelay);
    }
}

/*
System Information
*/
void UtilityController::handleSystem() {
    sysInfoShell.run();
}

/*
Firmware Guide (man)
*/
void UtilityController::handleGuide() {
    guideShell.run();
}

/*
Wizard
*/
void UtilityController::handleWizard(const TerminalCommand& cmd) {
    // Validate pin argument
    if (cmd.getSubcommand().empty() || !argTransformer.isValidNumber(cmd.getSubcommand())) {
        terminalView.println("Usage: wizard <pin>");
        return;
    }

    // Verify protected pin
    uint8_t pin = argTransformer.toUint8(cmd.getSubcommand());
    if (state.isPinProtected(pin)) {
        terminalView.println("Wizard: This pin is protected or reserved.");
        return;
    }

    terminalView.println("\nWizard: Please wait, analyzing pin " + std::to_string(pin) + "... Press [ENTER] to stop.\n");
    pinAnalyzeManager.begin(pin);
    const bool doPullTest = false; // TODO: add argument to enable pull test if needed

    while (true) {
        // Check for ENTER press to stop
        char key = terminalInput.readChar();
        if (key == '\r' || key == '\n') {
            terminalView.println("\nWizard: Stopped by user.");
            break;
        }

        // Sample pin
        for (int i = 0; i < 2048; i++) {
            pinAnalyzeManager.sample();
        }

        // Check if it's time to report and report activity
        if (pinAnalyzeManager.shouldReport(millis())) {
            auto report = pinAnalyzeManager.buildReport(doPullTest);
            terminalView.print(pinAnalyzeManager.formatWizardReport(pin, report));
            pinAnalyzeManager.resetWindow();
            terminalView.println("Wizard: Analyzing pin " + std::to_string(pin) + "... Press [ENTER] to stop.\n");
        }
    }

    // Cleanup buffers
    pinAnalyzeManager.end();
}

/*
Hex
*/
void UtilityController::handleHex(const TerminalCommand& cmd) {
    uint32_t value = 0;

    // Parse number if any
    if (!cmd.getSubcommand().empty()) {
        const std::string& s = cmd.getSubcommand();

        if (!argTransformer.isValidNumber(s)) {
            terminalView.println("Usage: hex <number>");
            return;
        }

        value = argTransformer.parseHexOrDec32(s);
    } else {
        // No number provided, ask user for input
        value = (uint32_t)userInputManager.readValidatedUint32("\nEnter a number or hex", 65);
    }

    // dec
    terminalView.println("\n  Dec   : " + std::to_string(value));

    // hex
    terminalView.println("  Hex   : 0x" + argTransformer.toHex(value, 0));

    // bin 
    terminalView.println("  Bin   : " + argTransformer.toBinString(value));

    // ASCII
    std::string ascii = argTransformer.toAsciiString(value);
    if (!ascii.empty()) {
        terminalView.println("  ASCII : " + ascii);
    }

    terminalView.println("");
}

/*
Profile
*/
void UtilityController::handleProfile() {
    profileShell.run();
}

/*
Help
*/
void UtilityController::handleHelp() {
    helpShell.run(state.getCurrentMode());
}

bool UtilityController::isGlobalCommand(const TerminalCommand& cmd) {
    std::string root = cmd.getRoot();

    return (root == "mode"  || root == "m" || root == "l" ||
            root == "logic" || root == "analogic" || root == "P" || root == "p") || 
            root == "system" || root == "guide" || root == "man" || root == "wizard" ||
            root == "help" || root == "h" || root == "?" || root == "hex" || root == "dec" ||
            root == "sys" || root == "profile";
}

bool UtilityController::isScreenCommand(const TerminalCommand& cmd) {
   return cmd.getRoot() == "config" || cmd.getRoot() == "setprotocol" || cmd.getRoot() == "trace"
       || cmd.getRoot() == "pullup" || cmd.getRoot() == "pulldown" || cmd.getRoot() == "reset"
       || cmd.getRoot() == "swap" || cmd.getRoot() == "logic" || cmd.getRoot() == "analogic";
}