Skip to content

bsikar/VASA

BranchesTags

Repository files navigation

VASA: Voice-Activated System Architecture

License: MIT Platform: MSP432 Language: Assembly Python: 3.8+

VASA is an integrated voice-activated microcontroller architecture. It combines natural language processing (NLP) on a host PC (running PyAudio and Hugging Face's Wav2Vec2 model) with serial communications, interfacing an Arduino Nano and a Texas Instruments MSP432P401R microcontroller (ARM Cortex-M4).

The speech command processed by the NLP model is dispatched over UART to the MSP432P401R, which dynamically controls hardware peripherals such as LEDs, motors, a piezo buzzer, and a 7-Segment Display (SSD) based on real-time sensor events.

📖 Table of Contents

🔍 Project Overview

The architecture divides responsibilities across three key nodes:

  1. Python NLP Engine (src/python/):
    • Captures speech input using PyAudio.
    • Leverages Hugging Face's pretrained Wav2Vec2 model (facebook/wav2vec2-base-960h) via PyTorch to perform live transcription.
    • Filters commands using fuzzy matching (fuzzywuzzy) into predefined actions.
    • Transmits matching command characters (e.g., '0', '1', '2', '3') to the serial port.
  2. Arduino Nano Relay (nano/):
    • Functions as an optional bridge or serial receiver/transmitter, relaying instructions to the primary controller.
  3. MSP432P401R Microcontroller (src/):
    • Receives commands over UART.
    • Low-level drivers written in ARM Unified Assembly handle pin settings, interrupts, hardware configuration, and delay timers.
    • Toggles LEDs, a piezo buzzer, and runs a countdown timer on a 7-Segment Display.
    • Demonstrates ADC reading via a floating pin (analog noise) to seed random number generation.

📁 Repository & Directory Structure

Here is an overview of the key folders and files in the repository:

Path Description
src/ Primary directory containing low-level assembly drivers and Python host files.
src/main.s Application entry point; initializes all peripherals and sits in a main loop.
src/configure_*.s Configuration routines in assembly for UART, Buzzer, IR Sensor, LEDs, SSD, and Delay timers.
src/set_*.s Control routines in assembly to toggle state or execute patterns (e.g. countdown timer).
src/process_rx_char.s Reads character from UART RX buffer, tests flags, and maps commands to functions.
src/python/ Python engine scripts executing ASR (Automatic Speech Recognition) and serial transmission.
lib/ CMSIS headers and startup/system initialization templates (system_msp432p401r.c, startup_msp432p401r_gcc.c).
nano/ Arduino Nano firmware sketches (uart-send.ino, python-send.ino).
Makefile GNU Make build configuration for compilation, flashing (OpenOCD), and QEMU emulation.
msp432p401r.lds Linker script defining flash/RAM memory maps for compilation.

📌 Port & Pin Mapping

Below is the pin assignment table on the MSP432P401R LaunchPad:

Peripherals & GPIO

Port & Pin Peripheral Mode / Function Driver Reference Details
P1.0 LED 1 (Red) configure_led1.s / set_led1.s Internal LaunchPad LED
P2.0 LED 2 (Red) configure_led2.s / set_led2.s Internal LaunchPad Multi-Color LED
P2.1 LED 2 (Green) configure_led2.s / set_led2.s Internal LaunchPad Multi-Color LED
P2.2 LED 2 (Blue) configure_led2.s / set_led2.s Internal LaunchPad Multi-Color LED
P1.2 UART RX (eUSCI_A0) uart_helper.c (Internal) Backchannel UART RX
P1.3 UART TX (eUSCI_A0) uart_helper.c (Internal) Backchannel UART TX
P3.2 UART RX (eUSCI_A2) configure_uart.s External Serial RX (linked to Nano)
P3.3 UART TX (eUSCI_A2) configure_uart.s External Serial TX (Unused)
P5.3 ADC (A2) Unconnected Pin Read for analog noise seeding
P5.4 GPIO Input configure_ir.s Connected to Infrared (IR) Sensor
P5.5 GPIO Output configure_buzzer.s / set_buzzer.s Connected to Piezo Buzzer
P4.7 GPIO Input set_seven_segment.s Nano Wait / Sync Signal

7-Segment Display (SSD)

The 7-Segment Display is Active Low (segments light up when the corresponding pin is driven to ground). It maps to Port 4 (Pins 0 to 6):

Segment Port & Pin Value to Enable (Active Low)
a (0) P4.0 0x01
b (1) P4.1 0x02
c (2) P4.2 0x04
d (3) P4.3 0x08
e (4) P4.4 0x10
f (5) P4.5 0x20
g (6) P4.6 0x40

⚙️ Environment Setup & Installation

Follow these steps to configure your developer environment for assembly compilation, flashing, and testing.

Prerequisites

Ubuntu / Debian-based Linux

sudo apt-get update
sudo apt-get install build-essential gcc make gcc-arm-none-eabi openocd gconf2 qemu-system-arm

Arch Linux

sudo pacman -S base-devel gcc make arm-none-eabi-gcc openocd dconf arm-none-eabi-newlib qemu-system-arm qemu-system-arm-firmware

Optional: For Arduino Compiler support

  • Debian/Ubuntu: sudo apt-get install gcc-avr avr-libc avrdude arduino-avr-core
  • Arch Linux: sudo pacman -S avr-gcc avr-libc avrdude arduino-avr-core

SDK & Toolchain Configuration

  1. Download the SimpleLink MSP432 SDK: Get version 3.40.01.02 from Texas Instruments SDK Downloads.

  2. Download Code Composer Studio (CCS): Version 12.5.0 is recommended, downloadable from TI Code Composer Studio.

  3. Configure Environment Variables: Add the SDK installation path to your shell configuration (e.g. ~/.bashrc or ~/.zshrc):

    export MSP432_HEADERS=/path/to/headers/
# Example:
export MSP432_HEADERS=/home/brighton/Documents/SDK/ti/msp432/simplelink_msp432p4_sdk_3_40_01_02/

    Apply variables by sourcing your shell config:

    source ~/.bashrc

Code Formatting

Ensure formatting consistency with standard clang-format definitions:

  • Linux / macOS: 
    ./format.sh
  • Windows (PowerShell): 
    powershell -ExecutionPolicy Bypass -File .\format.ps1

Serial Monitor Connection

To verify serial messages, connect via screen or CoolTerm:

screen /dev/ttyUSB0 115200

On Arch Linux, CoolTerm can be installed via AUR:

paru -S coolterm

🛠️ Build, Flash, and Simulation

The repository provides a Makefile to build binaries, flash the LaunchPad, and simulate code using QEMU.

Makefile Commands

Command Action
make Compiles all C and assembly source files, and links them into eset350_final.elf.
make clean Removes compiled object (.o) files, .elf binaries, and linker map files.
make flash Compiles the code and flashes it to the connected MSP432 target using OpenOCD.
make simulate Runs the .elf binary inside qemu-system-arm (targeting MPS2 Cortex-M3 architecture) and starts a GDB session attached to port :1234.
make debug Starts a debug session. Launches OpenOCD on port :3333 and executes arm-none-eabi-gdb with monitor connection commands.

Note

Set DEBUG=1 to compile with symbols (-g -O0) for debugging: make DEBUG=1

📖 Peripheral Reference Manual

UART Configuration

The external connection on Port 3 (Pin 2) is handled by the eUSCI_A2 serial module.

Control Word Register (CTLW0)

  • UCSWRST (Bit 0): Software Reset. Set to 1 during configuration; cleared to 0 to activate.
  • UCSSELx (Bits 9-8): Clock Source. Set to 10 or 11 to select SMCLK.
  • UC7BIT (Bits 2-1): Character Length. Set to 00 for 8-bit data.
  • UCPEN (Bit 0): Parity. Set to 0 to disable parity.

Interrupt Flag Register (IFG)

  • UCRXIFG (Bit 6): Receive Buffer Full. Set when new data has arrived in RXBUF.
  • UCTXIFG (Bit 7): Transmit Buffer Empty. Set when TXBUF is empty and ready for data.

Key Registers

  • BRW: Baud Rate Word. Sets the baud rate divisor.
  • MCTLW: Modulation Control Word. Fine-tunes baud rates and configures oversampling settings.

SPI Configuration

SPI Control Register (SPCR)

  • SPIE (Bit 7): Interrupt Enable. Toggles serial transfer completion interrupts.
  • SPE (Bit 6): SPI Enable. Must be 1 to run SPI bus operations.
  • DORD (Bit 5): Data Order. 1 = LSB First; 0 = MSB First.
  • MSTR (Bit 4): Master/Slave Mode. 1 = Master; 0 = Slave.
  • CPOL (Bit 3): Clock Polarity. 1 = Clock high when idle; 0 = Clock low.
  • CPHA (Bit 2): Clock Phase. 1 = Sample on trailing edge; 0 = Sample on leading edge.
  • SPR1, SPR0 (Bits 1-0): Clock Rate select (f_osc/4, f_osc/16, f_osc/64, f_osc/128).

SPI Status Register (SPSR)

  • SPIF (Bit 7): Transfer Complete Interrupt flag.
  • WCOL (Bit 6): Write Collision flag.
  • SPI2X (Bit 0): Double SPI speed.

Pins & Core Signals

  • SS (Slave Select): Master drives low to choose which target device to communicate with.
  • MISO / MOSI: Data lines for incoming and outgoing data.
  • SCK: Synchronization clock generated by the SPI Master.

I2C Configuration

Control Register (I2C_CR)

  • IEN (Bit 7): I2C Enable. Toggles the hardware interface.
  • IRPT (Bit 6): Interrupt Enable.
  • ACK (Bit 5): Acknowledge Control bit.
  • START (Bit 4) / STOP (Bit 3): Condition generation signals.
  • MODE (Bits 1-0): Speed select (Standard 100kHz, Fast 400kHz, Fast Plus 1MHz, High-Speed 3.4MHz).

Status Register (I2C_SR)

  • BUSY (Bit 7): Bus Active status.
  • ARLO (Bit 6): Arbitration Lost status.
  • ACK_RECEIVED (Bit 5): Acknowledge reception indicator.
  • TIMEOUT (Bit 2): Timeout error indicator.

ADC Configuration

Interfacing on Port 5 (Pin 3) uses the internal 14-bit ADC module (ADC14).

Control Register 0 (CTL0)

  • ADC14PDIV (Bits 15-14): Clock Pre-divider (1, 4, 32, or 64).
  • ADC14SHSx (Bits 13-12): Sample/Hold Trigger Source (Software trigger ADC14SC or Timer trigger).
  • ADC14CONSEQx (Bit 3): Sequence Mode (Single-channel, Sequence, Repeat-single, Repeat-sequence).
  • ADC14ON (Bit 0): Powers ADC on (1) or off (0).

Memory Control Register (MCTL)

  • ADC14INCHx (Bits 4-0): Analog Input Channel selection (maps to pins A0-A31).
  • ADC14DIF (Bit 7): 1 = Differential mode; 0 = Single-ended mode.

RFID-RC522 Module

Pinout configuration for interfacing the RC522 RFID module with MSP432:

  1. VCC: 3.3V Power Supply.
  2. RST: Reset Pin (Active Low).
  3. GND: Power Ground.
  4. MISO: SPI Master In Slave Out.
  5. MOSI: SPI Master Out Slave In.
  6. SCK: SPI Clock.
  7. NSS (CS): Slave Select (Active Low).
  8. IRQ: Interrupt Request (Optional, signals card detection).

🖥️ GDB & QEMU Simulation Guide

When running in simulation (make simulate) or debugging on hardware (make debug), use the following tools and commands.

GDB Commands Cheat Sheet

  • si (stepi) - Step instruction by instruction. Essential for assembly stepping.
  • ni (nexti) - Step over call. Runs subroutines as a single operation.
  • disassemble / disass - Show disassembled assembly code for a function.
    • Example: disassemble main or disassemble $pc (around current Program Counter).
  • info registers - Print the contents of all CPU registers.
    • Target specific register: info register $r0
  • set - Modify a register or memory location.
    • Example: set $r0 = 1
  • layout asm - Enter GDB Text User Interface (TUI) assembly layout mode.
  • layout regs - Enter TUI layout displaying assembly side-by-side with CPU register states.
  • tui enable - Enable TUI mode.

Examining Stack & Memory

Check memory content using the examine (x) command:

x/<Count><Format><Size> <Address>
  • Count: Number of units to show.
  • Format: x (hexadecimal), d (signed decimal), i (instruction).
  • Size: b (byte), h (half-word), w (word/4 bytes), g (giant/8 bytes).

Useful Commands

  • View call stack: backtrace (or bt) / info stack.
  • View local variables: info locals / info args.
  • Read 20 words from stack pointer: 
    x/20xw $sp
  • Inspect instructions at current PC: 
    x/10i $pc

Breakpoints

Set a breakpoint at a memory location, function name, or line:

  • By address: break *0xf0
  • Conditional breakpoint: break *0xf0 if $r0 == 5
  • Temporary breakpoint (deletes on trigger): tbreak *0xf0
  • Show breakpoints: info breakpoints

About

Voice Activated System Assistant

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages