unleashed-firmware/wiki/fw/Firmware.md

_Overview of Flipper firmware architecture:_

![FW arch](https://github.com/Flipper-Zero/wiki/raw/master/images/flipper_fw_arch.png)

# Project structure

.
+-- core                    # App
+-- target_f1               # target f1
+-- target_lo               # local target (for linux)
|	+-- sample1
|	+-- sample2
+-- wiki                    # Documentation (wiki) generates from this files
|	+-- sample1
|	+-- sample2
+-- wiki-deploy.sh          # Script to generate Wiki from local .md files


# HAL

We use STM32 HAL/LL. Description available here: [dm00105879.pdf](https://github.com/Flipper-Zero/wiki/raw/master/dm00105879-description-of-stm32f4-hal-and-ll-drivers-stmicroelectronics.pdf)

## Flipper HAL

Some flipper-specific implementation of gpio/HAL:

* Init gpio pin: `app_gpio_init`
* Fast write gpio (inline): `app_gpio_write`
* Fast read gpio (inline): `app_gpio_read`
* Microsecond delay `delay_us`
* Set PWM on timer's pin: `pwm_set`

Files location: `/app/app_hal.[ch]`

# OS

We use FreeRTOS 10.0.1 for sheduling. Documentation available on [freertos.org](https://www.freertos.org/a00106.html).

Files location for L476 version: `/target_prod/Middlewares/Third_Party/FreeRTOS`

**[Timers map](Timers)**

# Platform code

CMSIS, Freertos and HAL files are generated by CubeMX.
You can find platform code for L476 version in `target_prod` folder:

* `Drivers/STM32L4xx_HAL_Driver` – hardware abstraction layer  
* `Drivers/CMSIS` — ARM specific code
* `Inc` `Src` — CubeMX generated headers & code
* `Middlewares/Third_Party/FreeRTOS/Source` — freeRTOS
* `deploy.sh` — flash firmware to device
* `STM32L476RGTx_FLASH.ld` — linker script
* `startup_stm32l476xx.s` — board startup/initialization assembler code
* `flipperzero_l476.ioc` — CubeMX project file

You can regenerate platform code:
1. Download CubeMX from [st.com](https://www.st.com/en/development-tools/stm32cubemx.html)
2. Open `*.ioc` file
3. Click `generate code`
4. After regenerating, look at git status, regenerating may broke some files.

## Arduino compatibility

There are some arduino-style defines (digitalWrite, delay, etc.). Include `Arduino.h` from `/app/Arduino.h`

## Debug print

You can use `pintf` to write any message to debug UART. UART specify in `Makefile` as `-DDEBUG_UART=<>`.

Implementation of write method located at `/app/write.c`

# Flipper Universal Registry Implementation (FURI)

FURI is used to:

* application control (start, exit, switch between active)
* data exchange between application (create/open channel, subscribe and push messages or read/write values)
* non-volatile data storage for application (create/open value and read/write)

Read more at [FURI page](FURI)

# FS

File system is used to volaile storage some files (config, application data, etc.). There are some folders mounted to different volumes:

* `/usr` for store static data like assets, menu items. Build system add files to usr while building. It can be useful for exchange some static data between application. For example, your app can add link to itself to Plugins menu items file, user will see your app and can call it from this menu.
* Specially `/usr/etc-default` folder contains default configs for apps. Bootloader has `factory default` options to reset applications config. Also when new app is bootstapping, system copy files from default config folder to `/etc`.
* `/etc` for store configs of application. This volume not overwrite during flashing.
* `/var` for store some application data (saved keys, application database, logs). This volume also not overwrite during flashing.
* `/media/*` mounted if SD card is inserted.

# Flipper applications

Each flipper functionality except OS/HAL/FURI doing by Flipper application. Some application are called at startup, the rest are called by the user (for example, from menu).

**[List of Flipper applications](Flipper-applications)**

For exchange data between application each app expose own record in FURI. You can subscribe on/read record to get data from application and write to record to send data to application.

**[List of FURI records](FURI-records-list)**

# Flipper libraries

Unlike applications that run after startup, libraries are a collection of constants, types, or functions that the user can call from within the application.

**[List of Flipper libraries](Flipper-libraries)**

# Bootloader

After start, bootloader run first. It can:

1. Runs main firmware
2. Reflashes firmware from temporary area after updating from usb/bluetooth
3. Restores factory default firmware for protected flash area
4. Restores application settings to default by clearing `/etc` volume

# Building

## Build in docker container (main way)

1. Install [docker compose](https://docs.docker.com/compose/install/)
2. After startup you should run `docker-compose up -d` to run the container.
3. Then you can run `docker-compose exec dev make -C <target_dir>` to build application.

If Dockerfile is changed you should run `docker-compose down` and `docker-compose build` for rebuild the image.

### Local build and run

You can run firmware locally (with HAL stub).

* `docker-compose exec dev make -C target_lo` for build
* `docker-compose exec dev target_lo/build/target_lo` for run

## Build in IDE

* Arduino IDE (in progress)
* PlatformIO (in progress)