Increase CPU speed to 16 MHz. Add hardware documentation. (#6)

Author: xchrishawk

CMakeLists.txt

@@ -34,7 +34,7 @@ set(CMAKE_C_COMPILER                ${AVR_GCC})
 
 set(DEVICE_MCU                      atmega1284p
     CACHE STRING                    "The MCU model to compile for.")
-set(DEVICE_F_CPU                    8000000
+set(DEVICE_F_CPU                    16000000
     CACHE STRING                    "The device's CPU frequency, in Hz.")
 set(DEVICE_BAUD                     19200
     CACHE STRING                    "The default USART baud rate, in bits per second.")

Doxyfile.in

@@ -12,7 +12,8 @@
 
 PROJECT_NAME            = @PROJECT_NAME@
 OUTPUT_DIRECTORY        = @CMAKE_CURRENT_BINARY_DIR@/docs
-INPUT                   = @CMAKE_SOURCE_DIR@/readme.md \
+INPUT                   = @CMAKE_SOURCE_DIR@/readme.md                                  \
+                          @CMAKE_SOURCE_DIR@/doc                                        \
                           @CMAKE_SOURCE_DIR@/src
 RECURSIVE               = YES
 EXTRACT_ALL             = @DOXYGEN_EXTRACT_ALL@

doc/hardware.md

@@ -0,0 +1,90 @@
+# SuperKey Hardware
+
+This page describes the SuperKey's hardware.
+
+## Microcontroller
+
+The SuperKey uses an [ATmega1284P microcontroller](https://www.microchip.com/en-us/product/ATmega1284p), currently
+produced by [Microchip Technology](https://www.microchip.com/). The datasheet for the ATmega1284P is available at
+[this link](https://ww1.microchip.com/downloads/en/DeviceDoc/ATmega164A_PA-324A_PA-644A_PA-1284_P_Data-Sheet-40002070B.pdf).
+The microcontroller uses a [dual inline package (DIP)](https://en.wikipedia.org/wiki/Dual_in-line_package)
+configuration, since this is the easiest type of integrated circuit for hobbyists to work with.
+
+### Clock
+
+The device uses a crystal oscillator with a frequency of 16 MHz as its primary clock inputs. This is connected to the
+`XTAL1` and `XTAL2` pins as shown in the schematic.
+
+![Crystal Schematic](xtal.png "Crystal Schematic")
+
+### Fuses
+
+The microcontroller fuse configuration was calculated using [this site](https://www.engbedded.com/fusecalc/). The fuses
+are set for the following options:
+
+- External Crystal Oscillator
+  - Frequency 8.0+ MHz
+  - Start-up time 16K clocks + 0 ms
+- Enable SPI programming
+- Enable JTAG
+- Enable brown-out detection at 2.7 V
+
+This leads to the following fuse bytes:
+
+- Low: `0xDF`
+- High: `0x99`
+- Extended: `0xFD`
+
+The fuses can be programmed with the following `avrdude` command:
+
+```
+avrdude -c avrispmkii -P usb -p m1284p -U lfuse:w:0xdf:m -U hfuse:w:0x99:m -U efuse:w:0xfd:m
+```
+
+### Pinout
+
+The pinout for the ATmega1284P is shown below:
+
+![Device Pinout](pinout.png "Device Pinout")
+
+### Pin Assignments
+
+The current pin assignments are shown in the table below. Pins which are not listed are currently unassigned.
+
+| Pin | Function | Description                | Notes                     |
+|-----|----------|----------------------------|---------------------------|
+| 6   | `MOSI`   | SPI Controller Out         | Only used for programming |
+| 7   | `MISO`   | SPI Controller In          | Only used for programming |
+| 8   | `SCK`    | SPI Clock                  | Only used for programming |
+| 9   | `RESET`  | Reset Device               |                           |
+| 10  | `VCC`    | Power                      |                           |
+| 11  | `GND`    | Ground                     |                           |
+| 12  | `XTAL2`  | Crystal Oscillator Input 2 |                           |
+| 13  | `XTAL1`  | Crystal Oscillator Input 1 |                           |
+| 14  | `RXD0`   | Interface Port UART RX     |                           |
+| 15  | `TXD0`   | Interface Port UART TX     |                           |
+| 16  | `RXD1`   | Debug Port UART RX         |                           |
+| 17  | `TXD1`   | Debug Port UART TX         |                           |
+| 19  | `OC1A`   | Buzzer Output              |                           |
+| 20  | `PD6`    | Key LED                    | Active high               |
+| 21  | `PD7`    | Status LED                 | Active high               |
+| 30  | `AVCC`   | ADC Power                  | ADC is currently unused   |
+| 31  | `GND`    | Ground                     |                           |
+| 32  | `AREF`   | ADC Reference Voltage      | ADC is currently unused   |
+| 33  | `PA7`    | Output TRS Ring            |                           |
+| 34  | `PA6`    | Output TRS Tip             |                           |
+| 35  | `PA5`    | Input TRS 2 Ring           |                           |
+| 36  | `PA4`    | Input TRS 2 Tip            |                           |
+| 37  | `PA3`    | Input TRS 1 Ring           |                           |
+| 38  | `PA2`    | Input TRS 1 Tip            |                           |
+| 39  | `PA1`    | Input TRS 0 Ring           |                           |
+| 40  | `PA0`    | Input TRS 0 Tip            |                           |
+
+## Firmware Upload
+
+The executable is uploaded to the MCU using [`avrdude`](https://www.nongnu.org/avrdude/) and an
+[AVRISP mkII programmer](https://a.co/d/59zSwb5).
+
+```
+avrdude -c avrispmkii -P usb -p m1284p -U flash:w:superkey.ihex -D
+```

doc/pinout.png

@@ -0,0 +1,3 @@
+# SuperKey User's Guide
+
+This will be a user's guide some day.

doc/userguide.md

@@ -9,12 +9,11 @@ This will be a README someday.
 [![Build - AVR ATmega1284P (Debug)](https://github.com/xchrishawk/superkey/actions/workflows/build-atmega1284p-debug.yaml/badge.svg)](https://github.com/xchrishawk/superkey/actions/workflows/build-atmega1284p-debug.yaml)<br/>
 [![Build - AVR ATmega1284P (Release)](https://github.com/xchrishawk/superkey/actions/workflows/build-atmega1284p-release.yaml/badge.svg)](https://github.com/xchrishawk/superkey/actions/workflows/build-atmega1284p-release.yaml)
 
-## Notes
+## Documentation
 
-### Upload Command
+- [User's Guide](doc/userguide.md) - User-focused instruction manual for the SuperKey.
+- [Hardware](doc/hardware.md) - Description of SuperKey hardware and its configuration.
 
-The executable is uploaded to the MCU using [`avrdude`](https://www.nongnu.org/avrdude/) and an [AVRISP mkII programmer](https://a.co/d/59zSwb5).
+## Notes
 
-```
-avrdude -c avrispmkii -P usb -p m1284p -U flash:w:superkey.ihex -D
-```
+### Upload Command

doc/xtal.png

@@ -26,7 +26,7 @@
  * @def     DEBUG_TEST_CLOCK_WRAPAROUND
  * @brief   If set to `ON`, the system tick will be set to 15 seconds prior to a wraparound at startup.
  */
-#define DEBUG_TEST_CLOCK_WRAPAROUND     ON
+#define DEBUG_TEST_CLOCK_WRAPAROUND     OFF
 
 /* --------------------------------------------------- VARIABLES ---------------------------------------------------- */
 
@@ -105,22 +105,22 @@ void sys_init( void )
     //
     // Initialize timer 0 for main system tick at 1 millisecond period. Based on the following:
     //
-    // - F_CPU      = 8 MHz
-    // - P_CPU      = 1 / 8 MHz         = 0.125 us
+    // - F_CPU      = 16 MHz
+    // - P_CPU      = 1 / 16 MHz        = 62.5 ns
     // - Prescaler  = F_CPU / 64
-    // - P_TIMER    = 0.125 us * 64     = 8 us
-    // - Clocks     = 1 ms / 8 us       = 125
-    // - OCRA       = Clocks - 1        = 124
+    // - P_TIMER    = 0.05 us * 64      = 4 us
+    // - Clocks     = 1 ms / 4 us       = 250
+    // - OCRA       = Clocks - 1        = 249
     //
     // Therefore we have:
     //
     // - Waveform generation mode set to CTC
-    // - Clock prescaler set to F_CPU / 64 (F_CPU = 8 MHz)
-    // - Compare value set to 124
+    // - Clock prescaler set to F_CPU / 64 (F_CPU = 16 MHz)
+    // - Compare value set to 249
     //
     TCCR0A = bitmask1( WGM01 );
     TCCR0B = bitmask2( CS00, CS01 );
-    OCR0A = 124;
+    OCR0A = 249;
 
     // Enable interrupt for timer 0
     TIMSK0 = bitmask1( OCIE0A );