# Firmware

This will be a very barebones guide on just how to get started with firmware.

We will be using **Arduino IDE**, download it [here](https://www.arduino.cc/en/software/)

## What you'll need

Before we start, a few things need to be installed.

Follow the first few steps of the `Software Preparation` guide in the docs [here](https://wiki.seeedstudio.com/XIAO_ESP32C3_Getting_Started/) on how to install the ESP32 board in Arduino IDE

Install the following libraries:
- Adafruit_ST7735 and ST7789
- Adafruit_GFX

Use the library manager to install these! Install all the pre-reqs when the pop-up shows after you click install.

You're all done! In your new sketch, include the following:

```
#include <Adafruit_GFX.h>
#include <Adafruit_ST7789.h>
#include <SPI.h>
```

Inside `void setup()`, include the following:

`Serial.begin(115200);`

This makes sure that the ESP32 can communicate with the computer over serial.

As a general rule of thumb, if you would like to create a variable/object, it should go outside of any method, if you would like to set up something (e.g. it should only run once such as connecting to Wi-Fi), it should be in void setup(), if you would like something to run continuously, it should be in `void loop()`.

## TFT Screen

In this project, we will be using an ST7789 screen, but it has a bit of an unusual resolution, 284x76 as opposed to a traditional 240x320.

We need to define the pin variables that we will be connecting our screen to! Refer to the hardware section of the tutorial for the proper pin assignments. Create the variables as such:

```
#define TFT_SCLK 0 // labeled SCL on the screen
#define TFT_MOSI 1 // labeled SDA on the screen
#define TFT_RST 2
#define TFT_DC 3
#define TFT_CS 4
#define TFT_BL 5
```

The numbers 0-5 will be changed based on your pin assignments on the ESP32.

Create your screen object:

`Adafruit_ST7789 tft = Adafruit_ST7789(TFT_CS, TFT_DC, TFT_MOSI, TFT_SCLK, TFT_RST);`

You can change "tft" to anything you would like.

In your setup, initiate the screen:

```
tft.init(76, 284); // Our panel size (portrait)
tft.setOffsets(82, 18); // Offsets for the weird resolution
tft.invertDisplay(false); // Invert the colors (This display is flipped from normal)
tft.setRotation(1); // Landscape, if it's upside down use 3!
tft.fillScreen(ST77XX_BLACK); // clear the screen
Serial.println("TFT Initialized!");
tft.setCursor(0,0); // make the cursor at the top left
```

## loop()
Every sketch needs two functions to compile: `setup()`, which runs once when the board powers on, and `loop()`, which runs over and over, forever, the moment `setup()` finishes.
```
void loop() {
  // Your code goes here. Anything in here repeats forever!
}
```
This is where continuous behavior lives: checking a button, updating the screen, blinking an LED. You might want to put a `delay(ms)` to slow things down if your code is running too fast. (`delay(1000)` waits one second).

## General Methods

```
tft.print("STRING HERE");  // prints out the string
tft.setCursor(x,y);        // the screen is 284x76! Think of it as a x,y grid
tft.fillScreen(ST77XX_COLOR); // most of the main colors are here!
tft.drawRect(Cursorx, Cursory, RectWidth, RectHeight, ST77XX_color); // draws a rectangle
tft.fillRect(Cursorx, Cursory, RectWidth, RectHeight, ST77XX_color); // fills in a rectangle
tft.setTextSize(integer);  // try it out! Use 1,2,3, etc.
```

## Complete Example
```
#include <Adafruit_GFX.h> // graphics library
#include <Adafruit_ST7789.h> // driver for the ST7789 screen
#include <SPI.h> 

// Defining pins for the display, change according to your setup!!! Uses the white numbers on the ESP
#define TFT_SCLK 0 // labeled SCL on the screen
#define TFT_MOSI 1 // labeled SDA on the screen
#define TFT_RST 2
#define TFT_DC 3
#define TFT_CS 4
#define TFT_BL 5

// Fix setColRowStart() by exposing it via a subclass
class MyST7789 : public Adafruit_ST7789 {
public:
  MyST7789(int8_t cs, int8_t dc, int8_t mosi, int8_t sclk, int8_t rst)
    : Adafruit_ST7789(cs, dc, mosi, sclk, rst) {}
  void setOffsets(uint8_t col, uint8_t row) {
    _colstart = _colstart2 = col;
    _rowstart = _rowstart2 = row;
  }
};

MyST7789 tft(TFT_CS, TFT_DC, TFT_MOSI, TFT_SCLK, TFT_RST);

// setup() runs ONCE when the board powers on
void setup() {
  Serial.begin(115200); // lets the board talk to your computer

  pinMode(TFT_BL, OUTPUT); // Set the backlight pin mode, or just wire it to 3.3V
  digitalWrite(TFT_BL, LOW); // Turns the backlight ON, for some reason this screen is active Low, so setting it to LOW is really HIGH

  tft.init(76, 284); // Our panel size (portrait)
  tft.setOffsets(82, 18); // Offsets for the weird resolution
  tft.invertDisplay(false); // Invert the colors (This display is flipped from normal)
  tft.setRotation(1); // Landscape, if it's upside down use 3!
  Serial.println("TFT Initialized!");

  tft.fillScreen(ST77XX_BLACK); // clear the screen

  tft.setTextColor(ST77XX_WHITE);
  tft.setTextSize(6);
  tft.setCursor(0,0); // Where the text is drawn, 0,0 is top left
  tft.print(42); // Show whatever you want! Draws from the top left of the text/number/shape 
}

// loop() runs OVER and OVER, forever
void loop() {
  // add your code here!
}
```

When you're done with your firmware, get ready to submit your project [here](/docs/blare/submitting-your-project).