diff --git a/EnvironmentSetup.md b/EnvironmentSetup.md deleted file mode 100644 index 53055ab..0000000 --- a/EnvironmentSetup.md +++ /dev/null @@ -1,55 +0,0 @@ -# msp432 - -## used version 3.40.01.02 -[https://www.ti.com/tool/download/SIMPLELINK-MSP432-SDK/3.40.01.02](https://www.ti.com/tool/download/SIMPLELINK-MSP432-SDK/3.40.01.02) - -## used version 12.5.0 -[https://www.ti.com/tool/CCSTUDIO#downloads](https://www.ti.com/tool/CCSTUDIO#downloads) - - -## formatting -linux: `./format.sh` - -windows: `powershell -ExecutionPolicy Bypass -File .\format.ps1` - - -## install - -### packages -``` -sudo apt-get install build-essential gcc make gcc-arm-none-eabi openocd gconf2 -sudo pacman -S base-devel gcc make arm-none-eabi-gcc openocd dconf arm-none-eabi-newlib - -sudo pacman -S qemu-system-arm qemu-system-arm-firmware -``` - -#### if Arduino is used -``` -sudo apt-get install gcc-avr avr-libc avrdude arduino-avr-core -sudo pacman -S avr-gcc avr-libc avrdude arduino-avr-core -``` - -### SDK -[https://www.ti.com/tool/download/SIMPLELINK-MSP432-SDK/3.40.01.02](https://www.ti.com/tool/download/SIMPLELINK-MSP432-SDK/3.40.01.02) -Select a dir to download to, I choose `/home/brighton/Documents/SDK/msp432/ti` - -### Link -In your `~/.bashrc` add: -``` -export MSP432_HEADERS=/path/to/headers/ -# for example -export MSP432_HEADERS=/home/brighton/Documents/SDK/ti/msp432/simplelink_msp432p4_sdk_3_40_01_02/ -``` -Then source: `source ~/.bashrc` - -### Connect -``` -screen -screen /dev/ttyUSB0 115200 -``` -or use cool term -``` -sudo pacman -S paru -paru coolterm -``` - diff --git a/README.md b/README.md index e63d7dc..d955c93 100644 --- a/README.md +++ b/README.md @@ -1,426 +1,326 @@ +# VASA: Voice-Activated System Architecture + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Platform: MSP432](https://img.shields.io/badge/Platform-MSP432-blue.svg)](https://www.ti.com/tool/MSP-EXP432P401R) +[![Language: Assembly](https://img.shields.io/badge/Language-Assembly-orange.svg)](#) +[![Python: 3.8+](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](#) + +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](#-project-overview) +- [πŸ“ Repository & Directory Structure](#-repository--directory-structure) +- [πŸ“Œ Port & Pin Mapping](#-port--pin-mapping) +- [βš™οΈ Environment Setup & Installation](#%EF%B8%8F-environment-setup--installation) + - [Prerequisites](#prerequisites) + - [SDK & Toolchain Configuration](#sdk--toolchain-configuration) + - [Code Formatting](#code-formatting) +- [πŸ› οΈ Build, Flash, and Simulation](#%EF%B8%8F-build-flash-and-simulation) + - [Makefile Commands](#makefile-commands) +- [πŸ“– Peripheral Reference Manual](#-peripheral-reference-manual) + - [UART Configuration](#uart-configuration) + - [SPI Configuration](#spi-configuration) + - [I2C Configuration](#i2c-configuration) + - [ADC Configuration](#adc-configuration) + - [RFID-RC522 Module](#rfid-rc522-module) +- [πŸ–₯️ GDB & QEMU Simulation Guide](#%EF%B8%8F-gdb--qemu-simulation-guide) + - [GDB Commands Cheat Sheet](#gdb-commands-cheat-sheet) + - [Examining Stack & Memory](#examining-stack--memory) + - [Breakpoints](#breakpoints) + +--- + +## πŸ” 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/`](file:///Users/cesarmagana/Documents/GitHub/VASA/src)** | Primary directory containing low-level assembly drivers and Python host files. | +| **[`src/main.s`](file:///Users/cesarmagana/Documents/GitHub/VASA/src/main.s)** | Application entry point; initializes all peripherals and sits in a main loop. | +| **[`src/configure_*.s`](file:///Users/cesarmagana/Documents/GitHub/VASA/src)** | Configuration routines in assembly for UART, Buzzer, IR Sensor, LEDs, SSD, and Delay timers. | +| **[`src/set_*.s`](file:///Users/cesarmagana/Documents/GitHub/VASA/src)** | Control routines in assembly to toggle state or execute patterns (e.g. countdown timer). | +| **[`src/process_rx_char.s`](file:///Users/cesarmagana/Documents/GitHub/VASA/src/process_rx_char.s)** | Reads character from UART RX buffer, tests flags, and maps commands to functions. | +| **[`src/python/`](file:///Users/cesarmagana/Documents/GitHub/VASA/src/python)** | Python engine scripts executing ASR (Automatic Speech Recognition) and serial transmission. | +| **[`lib/`](file:///Users/cesarmagana/Documents/GitHub/VASA/lib)** | CMSIS headers and startup/system initialization templates (`system_msp432p401r.c`, `startup_msp432p401r_gcc.c`). | +| **[`nano/`](file:///Users/cesarmagana/Documents/GitHub/VASA/nano)** | Arduino Nano firmware sketches (`uart-send.ino`, `python-send.ino`). | +| **[`Makefile`](file:///Users/cesarmagana/Documents/GitHub/VASA/Makefile)** | GNU Make build configuration for compilation, flashing (OpenOCD), and QEMU emulation. | +| **[`msp432p401r.lds`](file:///Users/cesarmagana/Documents/GitHub/VASA/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 +```bash +sudo apt-get update +sudo apt-get install build-essential gcc make gcc-arm-none-eabi openocd gconf2 qemu-system-arm +``` -![Final Design](./photos/Final_Design.jpg) - - -## Project Overview - -NLP will be used on a Arduino Nano, then over UART 0, 1, 2 will be sent to the msp432p401r. -This data will then turn on the LEDs, turn on/off a motor and turn on/off a buzzer if a sensor is active. -The LED will be set to a random value by using a noisy unconnected pin and reading ADC - -## (Port.Pin)'s - -PM_ == Peripheral Mode / Port Mapping -UCAx == eUSCI_Ax -UCBx == eUSCI_Bx - -### Serial IO and Board-to-Board Communiation (UART) -- **P1.2**: UART RX (eUSCI_A0 / UCA0RXD) (internal) [used in uart_helper.c] -- **P1.3**: UART TX (eUSCI_A0 / UCA0TXD) (internal) [used in uart_helper.c] -- **P3.2**: UART RX (eUSCI_A2 / PM_UCA2RXD) [used in process_configure_uart.s] -- **P3.3**: UART TX (eUSCI_A2 / PM_UCA2TXD) [not used in this project] - -### On board LEDs -- **P1.0**: RED LED (LED1) (internal) -- **P2.0**: RED LED (LED2) (internal) [used in configure_led.s] -- **P2.1**: GREEN LED (LED2) (internal) [used in configure_led.s] -- **P2.2**: BLUE LED (LED2) (internal) [used in configure_led.s] - -### ADC (ADC14, 14 bit resolution) -- **P5.3**: ADC (ADC14MCTL2 / A2) (not connected to anything) - -### Additional Peripherals -- **P5.4**: GPIO (IR Sensor) -- **P5.5**: GPIO (PIEZO Buzzer) -- **P4.7**: GPIO (Nano Wait Signal) - -### 7-Segment-Display (SSD) Mapping -- **P4.0**: GPIO (SSD) 0 -- **P4.1**: GPIO (SSD) 1 -- **P4.2**: GPIO (SSD) 2 -- **P4.3**: GPIO (SSD) 3 -- **P4.4**: GPIO (SSD) 4 -- **P4.5**: GPIO (SSD) 5 -- **P4.6**: GPIO (SSD) 6 - -## UART (Universal Asynchronous Receiver/Transmitter) - -### CTLW0 (Control Word Register 0) -- **Bit 15 - UCSWRST (Software Reset)** - - `1` - UART held in reset state, useful during configuration. - - `0` - UART operational, reset released. -- **Bits 14-10 - Reserved** -- **Bits 9-8 - UCSSELx (Clock Source Select)** - - `00` - UCLKI (external clock). - - `01` - ACLK (auxiliary clock). - - `10` - SMCLK (sub-main clock). - - `11` - SMCLK. -- **Bit 7 - UCTXBRK (Transmit Break)** - - `1` - Send a break (low state) after transmitting the next character. - - `0` - No break transmitted. -- **Bit 6 - UCTXADDR (Transmit Address)** - - `1` - Next character transmitted is an address. - - `0` - Normal data transmission. -- **Bit 5 - UCDORM (Dormant)** - - `1` - Receiver ignores incoming data not addressing it. - - `0` - Normal operation. -- **Bit 4 - UCBRKIE (Receive Break Character Interrupt Enable)** - - `1` - Interrupt on received break character. - - `0` - No interrupt for break character. -- **Bit 3 - UCRXEIE (Receive Erroneous-Character Interrupt Enable)** - - `1` - Interrupt on erroneous character received. - - `0` - No interrupt on erroneous characters. -- **Bits 2-1 - UC7BIT (Character Length)** - - `00` - 8-bit data. - - `01` - 7-bit data. -- **Bit 0 - UCPEN (Parity Enable)** - - `1` - Parity enabled. - - `0` - No parity. - -### IFG (Interrupt Flag Register) -- **Bit 15-8 - Reserved** -- **Bit 7 - UCTXIFG (Transmit Buffer Empty Interrupt Flag)** - - `1` - Transmit buffer is empty, ready for new data. - - `0` - Transmit buffer not empty. -- **Bit 6 - UCRXIFG (Receive Buffer Full Interrupt Flag)** - - `1` - Receive buffer is full, contains unread data. - - `0` - Receive buffer not full. -- **Bits 5-0 - Reserved/Other Specific Flags** - -### Additional Registers (Brief Overview) -- **BRW (Baud Rate Word)** - - Sets the baud rate divisor based on the input clock. -- **MCTLW (Modulation Control Word)** - - Fine-tunes the baud rate via modulation settings; includes bits for oversampling. -- **TXBUF (Transmit Buffer)** - - Buffer for data to be transmitted. -- **RXBUF (Receive Buffer)** - - Buffer holding received data. -- **IE (Interrupt Enable Register)** - - Enables interrupts for specific UART events. -- **IV (Interrupt Vector Register)** - - Indicates the vector of the highest priority interrupt. -- **ABCTL (Auto Baud Rate Control)** - - Automatic baud rate detection feature. -- **IRCTL (Infrared Control Register)** - - Configures UART for infrared communication. - -## SPI (Serial Peripheral Interface) - -### SPI Control Register (SPCR) -- **Bit 7 - SPIE (SPI Interrupt Enable)** - - `1` - Enables the SPI interrupt when a serial transfer is complete. - - `0` - Disables the SPI interrupt. -- **Bit 6 - SPE (SPI Enable)** - - `1` - Enables the SPI bus; must be set to enable any SPI operations. - - `0` - Disables the SPI bus. -- **Bit 5 - DORD (Data Order)** - - `1` - LSB (Least Significant Bit) first. - - `0` - MSB (Most Significant Bit) first. -- **Bit 4 - MSTR (Master/Slave Select)** - - `1` - Sets the SPI bus configuration to Master. - - `0` - Sets the SPI bus configuration to Slave. -- **Bit 3 - CPOL (Clock Polarity)** - - `1` - The clock is high when idle. - - `0` - The clock is low when idle. -- **Bit 2 - CPHA (Clock Phase)** - - `1` - Data is sampled on the trailing edge of the clock. - - `0` - Data is sampled on the leading edge of the clock. -- **Bits 1-0 - SPR1, SPR0 (SPI Clock Rate Select)** - - `00` - f_osc/4 (where f_osc is the oscillator frequency). - - `01` - f_osc/16. - - `10` - f_osc/64. - - `11` - f_osc/128. - -### SPI Status Register (SPSR) -- **Bit 7 - SPIF (SPI Interrupt Flag)** - - This bit is set by hardware when a serial transfer is complete. Used to handle interrupts. -- **Bit 6 - WCOL (Write Collision Flag)** - - `1` - Indicates a write collision has occurred. - - `0` - No collision. -- **Bit 0 - SPI2X (Double SPI Speed Bit)** - - `1` - SPI speed is doubled. - - `0` - Normal SPI speed. - -### SPI Data Register (SPDR) -- **Functionality** - - This register is used for data transmission and reception. Writing to this register starts data transmission. Reading from this register reads the data received. - -### Additional SPI Features -- **SS Pin (Slave Select)** - - In master mode, this pin must be managed (usually driven low) to select a slave device before starting communication. -- **MISO (Master In Slave Out)** - - This is the data line for sending data from slave to master. -- **MOSI (Master Out Slave In)** - - This is the data line for sending data from master to slave. -- **SCK (Serial Clock)** - - Clock line controlled by the master, used to synchronize data transmission. - -## IIC / I2C (Inter-Integrated Circuit) - -### Control Register (I2C_CR) -- **Bit 7 - IEN (I2C Enable)** - - `1` - Enables the I2C module. - - `0` - Disables the I2C module. -- **Bit 6 - IRPT (Interrupt Enable)** - - `1` - Enables the generation of interrupts. - - `0` - Disables interrupts. -- **Bit 5 - ACK (Acknowledge Control)** - - `1` - Sends acknowledge when the acknowledge bit is required. - - `0` - Does not send an acknowledge. -- **Bit 4 - START (Start Condition)** - - `1` - Generates a start condition. - - `0` - Does not generate. -- **Bit 3 - STOP (Stop Condition)** - - `1` - Generates a stop condition. - - `0` - Does not generate. -- **Bit 2 - INT_FLAG (Interrupt Flag)** - - This bit is set by hardware when an interrupt condition occurs. Must be cleared by software. -- **Bits 1-0 - MODE (Operating Mode)** - - `00` - Standard mode (100 kHz) - - `01` - Fast mode (400 kHz) - - `10` - Fast mode plus (1 MHz) - - `11` - High-speed mode (3.4 MHz) - -### Status Register (I2C_SR) -- **Bit 7 - BUSY (Bus Busy)** - - `1` - Indicates that the bus is busy. - - `0` - Indicates that the bus is free. -- **Bit 6 - ARLO (Arbitration Lost)** - - `1` - The device lost arbitration and control of the bus. - - `0` - The device has control or arbitration not applicable. -- **Bit 5 - ACK_RECEIVED (Acknowledge Received)** - - `1` - Acknowledge was received after sending a byte. - - `0` - No acknowledge received. -- **Bit 4 - OVR (Overrun/Underrun)** - - `1` - Data was lost because of an overrun or underrun. - - `0` - No data was lost. -- **Bit 3 - PEC_ERR (PEC Error in Reception)** - - `1` - Packet Error Checking code does not match. - - `0` - No error detected. -- **Bit 2 - TIMEOUT (Timeout Error)** - - `1` - Timeout error occurred. - - `0` - No timeout error. -- **Bit 1-0 - Reserved** - -### Data Register (I2C_DR) -- **Functionality** - - This register holds the data to be transmitted or received. Data written to this register is queued for transmission; reading from this register gives the last received data. - -### Address Register (I2C_AR) -- **Functionality** - - Sets the device address in master mode or the response address in slave mode. Can usually be configured to use 7-bit or 10-bit addressing. - -### Additional I2C Features -- **SCL (Serial Clock Line)** - - The line over which the clock signal is transmitted. Controlled by the master. -- **SDA (Serial Data Line)** - - The line over which data is transmitted. It’s bidirectional and used for both sending and receiving data. -- **Master/Slave Mode** - - Devices on an I2C bus can act as either a master or a slave. The master controls the clock and initiates communication. - -## ADC (Analog-to-Digital Converter) - -### CTL0 (Control Register 0) -- **Bit 15-14 - ADC14PDIV (Pre-divider)** - - `00` - Pre-divider of 1. - - `01` - Pre-divider of 4. - - `10` - Pre-divider of 32. - - `11` - Pre-divider of 64. -- **Bits 13-12 - ADC14SHSx (Sample/Hold Source)** - - `00` - ADC14SC bit (software trigger). - - `01` - Timer trigger. - - `10` - Other external triggers. -- **Bits 11-10 - ADC14SHP (Sample/Hold Pulse Mode)** - - `0` - Sample-and-hold source determined by ADC14SHSx bits. - - `1` - Sample-and-hold signal sourced from the sampling timer. -- **Bits 9-8 - ADC14DIVx (Clock Divider)** - - `00` - Divider of 1. - - `01` - Divider of 2. - - `10` - Divider of 4. - - `11` - Divider of 8. -- **Bits 7-5 - Reserved** -- **Bit 4 - ADC14SSELx (Clock Source Select)** - - `0` - MODOSC (modulator oscillator). - - `1` - SMCLK (sub-main clock). -- **Bit 3 - ADC14CONSEQx (Conversion Sequence Mode)** - - `00` - Single-channel, single-conversion. - - `01` - Sequence-of-channels. - - `10` - Repeat-single-channel. - - `11` - Repeat-sequence-of-channels. -- **Bit 2 - ADC14BUSY (ADC Busy)** - - `1` - ADC is active. - - `0` - ADC is inactive. -- **Bit 1 - Reserved** -- **Bit 0 - ADC14ON (ADC On/Off)** - - `1` - ADC is on. - - `0` - ADC is off. - -### MCTL (Memory Control Register) -- **Bit 15-12 - ADC14WINCTH (Window Comparator High Threshold)** -- **Bit 11-8 - ADC14WINCCTL (Window Comparator Low Threshold)** -- **Bit 7 - ADC14DIF (Differential Mode)** - - `1` - Differential mode enabled. - - `0` - Single-ended mode. -- **Bits 6-5 - Reserved** -- **Bits 4-0 - ADC14INCHx (Input Channel Select)** - - `00000` - A0. - - `00001` - A1. - - Various other codes for additional analog channels. - -### Conversion Process -- **Start Conversion:** Triggered by software or a dedicated hardware signal. -- **Sampling:** The ADC samples the analog signal based on the selected input channel. -- **Conversion:** The sampled value is converted into a digital number, reflecting the signal's intensity. - -### Additional Features -- **Interrupts:** The ADC can be configured to generate interrupts at the end of a conversion, when a certain threshold is reached, or if an error occurs. -- **Low-Power Modes:** Designed for efficient operation, the ADC can be shut down or operate in a reduced power mode when not actively converting, saving energy in battery-powered applications. - -## RFID-RC522 -1. **VCC**: This is the power supply pin. It's connected to a positive voltage source. For the RFID-RC522, this is usually a 3.3V power supply. - -2. **RST**: This stands for Reset. It is used to reset the RFID module. Applying a low signal to this pin resets the internal states of the module. - -3. **GND**: This is the Ground pin. It is connected to the ground of the power supply and is used as a reference point for all signals. - -4. **MISO**: This stands for Master In Slave Out. It is used in SPI (Serial Peripheral Interface) communication. This pin is used by the RFID module to send data back to the microcontroller. - -5. **MOSI**: This stands for Master Out Slave In. It is also used in SPI communication. This pin is used by the microcontroller to send data to the RFID module. - -6. **SCK**: This stands for Serial Clock. It is another pin used in SPI communication. This clock signal is provided by the microcontroller to synchronize data transmission between the microcontroller and the RFID module. - -7. **NSS**: This stands for Negative Slave Select (also known as Chip Select or CS). It is used in SPI communication to activate the RFID module. It is typically active low, meaning the RFID module is selected for communication when this pin is pulled to a low logic level. - -8. **IRQ**: This stands for Interrupt Request. This pin is used by the RFID module to alert the microcontroller of certain events (like the presence of an RFID tag in its vicinity). It is an optional connection, not always used in every project. - -## Simulate/GDB -1. **`si` (stepi)** - Steps one instruction at a time. This is your primary tool for moving through assembly code instruction by instruction. - -2. **`ni` (nexti)** - Steps over the instruction; if the instruction is a function call, `ni` executes the whole function as a single step, unlike `si` which would step into the function. - -3. **`disassemble` / `disass`** - Displays the assembly code for a specific function or memory range. You can use it like `disassemble function_name` or `disassemble $pc` to see the assembly at the current program counter. +#### Arch Linux +```bash +sudo pacman -S base-devel gcc make arm-none-eabi-gcc openocd dconf arm-none-eabi-newlib qemu-system-arm qemu-system-arm-firmware +``` -4. **`x`** - Examines memory at a given address. It's versatile for inspecting memory in various formats and units. For example, `x/10i $pc` displays 10 instructions starting from the program counter. +#### 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](https://www.ti.com/tool/download/SIMPLELINK-MSP432-SDK/3.40.01.02). + +2. **Download Code Composer Studio (CCS)**: + Version `12.5.0` is recommended, downloadable from [TI Code Composer Studio](https://www.ti.com/tool/CCSTUDIO#downloads). + +3. **Configure Environment Variables**: + Add the SDK installation path to your shell configuration (e.g. `~/.bashrc` or `~/.zshrc`): + ```bash + 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: + ```bash + source ~/.bashrc + ``` + +### Code Formatting +Ensure formatting consistency with standard `clang-format` definitions: +* **Linux / macOS**: + ```bash + ./format.sh + ``` +* **Windows (PowerShell)**: + ```powershell + powershell -ExecutionPolicy Bypass -File .\format.ps1 + ``` -5. **`info registers`** - Shows the current values of all registers. You can also examine a specific register by using `info register $eax`, for instance, to see the value of the `eax` register. +### Serial Monitor Connection +To verify serial messages, connect via `screen` or `CoolTerm`: +```bash +screen /dev/ttyUSB0 115200 +``` +On Arch Linux, CoolTerm can be installed via AUR: +```bash +paru -S coolterm +``` -6. **`set`** - Allows you to modify the values of registers or variables. For example, `set $eax = 0x1` sets the `eax` register to 1. +--- -7. **`break`** - Sets a breakpoint at a specific line or function or address. In assembly, you might set it at a specific instruction address, like `break *0x00400576`. +## πŸ› οΈ Build, Flash, and Simulation -8. **`continue` (c)** - Continues running the program until the next breakpoint or the end of the program. +The repository provides a [`Makefile`](file:///Users/cesarmagana/Documents/GitHub/VASA/Makefile) to build binaries, flash the LaunchPad, and simulate code using QEMU. -9. **`layout asm`** - Switches the GDB layout to show the assembly code. This view is helpful for visualizing where in the code you are as you step through instructions. +### Makefile Commands -10. **`layout regs`** - Shows both the assembly code and the current state of registers. It's particularly useful for seeing how each instruction affects the registers. +| 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. | -11. **`info proc mappings`** - Useful for viewing the memory mapping of the process, which helps in understanding where different parts of your code and data are located in memory. +> [!NOTE] +> Set `DEBUG=1` to compile with symbols (`-g -O0`) for debugging: `make DEBUG=1` -12. **`tui enable`** - Activates the Text User Interface, making it easier to visualize code, registers, and source (if available). +--- -### Displaying the Stack -In GDB, displaying the stack can provide crucial insights into the state of your program, especially when debugging complex issues involving function calls and memory management. Here are several ways to display the stack in GDB: +## πŸ“– Peripheral Reference Manual -### 1. Using `info stack` or `bt` (backtrace) +### UART Configuration +The external connection on **Port 3 (Pin 2)** is handled by the `eUSCI_A2` serial module. -These commands display the call stack with function names, source file names, and line numbers, assuming debugging symbols are available. +#### 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. -- **`info stack`** or **`info frame`**: Shows a detailed stack frame, which includes function names, arguments, and locals. - - - Example command: - ```bash - (gdb) info stack - ``` +#### 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. -- **`bt`** or **`backtrace`**: Shows the call stack. You can limit the number of frames shown by specifying a number (e.g., `bt 10`). +#### Key Registers +* `BRW`: Baud Rate Word. Sets the baud rate divisor. +* `MCTLW`: Modulation Control Word. Fine-tunes baud rates and configures oversampling settings. - - Example command: - ```bash - (gdb) bt - ``` +--- -### 2. Examining the Stack Pointer +### SPI Configuration -You can display the contents around the current stack pointer using the `x` command, which is used to examine memory in various formats: +#### 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`). -- **`x/NFU ADDR`**: - - `N` tells GDB how many units to display. - - `F` specifies the display format (`x` for hexadecimal, `d` for signed decimal, and so on). - - `U` specifies the unit size (`b` for byte, `h` for halfword, `w` for word, `g` for giant/8 bytes). - - `ADDR` is the address to start displaying from, often the stack pointer. +#### SPI Status Register (`SPSR`) +- **SPIF (Bit 7)**: Transfer Complete Interrupt flag. +- **WCOL (Bit 6)**: Write Collision flag. +- **SPI2X (Bit 0)**: Double SPI speed. -For example, to display 20 words at the current stack pointer: -```bash -(gdb) x/20xw $sp -``` -or for a more typical 64-bit system: -```bash -(gdb) x/20xg $rsp -``` +#### 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. -### 3. Display Stack in a More Structured Way +--- -If you want to see local variables along with their values for a particular frame, you can use: +### I2C Configuration -- **`info locals`**: Shows the local variables of the current function. - - - Example command: - ```bash - (gdb) info locals - ``` +#### 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`). -- **`info args`**: Shows the arguments passed to the current function. +#### 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. - - Example command: - ```bash - (gdb) info args - ``` +--- -### 4. Displaying Specific Stack Frames +### ADC Configuration +Interfacing on **Port 5 (Pin 3)** uses the internal 14-bit ADC module (`ADC14`). -You can also switch to a specific frame to examine its contents more closely: +#### 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`). -- **`frame N`**: Switch to frame number `N`. +#### 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. - - Example command: - ```bash - (gdb) frame 2 - ``` - -After switching, you can use `info locals`, `info args`, or `x` commands to inspect the state of that particular frame. - -These methods allow you to explore the stack in various levels of detail, helping to diagnose issues related to function calls, recursion, memory corruption, and more. - -### Breaking -To set a breakpoint at a specific memory address in GDB, such as `0xf0`, you use the `break` command with the `*` symbol to indicate that you are specifying an address, not a function name or line number. Here's how you can do it: +--- +### 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: ```bash -(gdb) break *0xf0 +x/
``` - -This command tells GDB to insert a breakpoint at the memory address `0xf0`. When the program execution reaches this address, GDB will pause the execution, allowing you to inspect the program state, examine variables, and step through the code further. - -### Additional Details - -- **Conditional Breakpoints:** If you want to set a breakpoint that only triggers under certain conditions, you can add a condition to the breakpoint. For example, to break at address `0xf0` only when a certain register `eax` equals `5`, you would do: - - ```bash - (gdb) break *0xf0 if $eax == 5 +* **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**: + ```gdb + x/20xw $sp ``` - -- **Temporary Breakpoints:** If you only need the breakpoint once, you can make it temporary so that it automatically deletes itself after triggering: - - ```bash - (gdb) tbreak *0xf0 - ``` - -- **Checking Breakpoints:** After setting breakpoints, you can check where they are set using: - - ```bash - (gdb) info breakpoints +- **Inspect instructions at current PC**: + ```gdb + x/10i $pc ``` -This will list all the breakpoints you have set along with their conditions and hit counts. - -Setting breakpoints at specific addresses is particularly useful when debugging low-level code, such as operating systems or embedded systems code, where execution paths are not straightforward, or source code may not be directly available. +### 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`