mirrors/unleashed-firmware
1
Fork 0
mirror of https://github.com/DarkFlippers/unleashed-firmware.git synced 2025-12-12 04:34:43 +04:00
Code Issues Activity

Merge branch 'ofw_dev' into dev p1

Browse Source
This commit is contained in:
MX
2024-03-10 23:35:44 +03:00
parent 4e7f25a539
commit 58cd56a439
73 changed files with 958 additions and 229 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
documentation/.gitignore vendored
View File

@@ -1,2 +1 @@
/html
/latex
/doxygen/build

32
documentation/AppManifests.md
View File

@@ -1,14 +1,14 @@
# Flipper Application Manifests (.fam)
# Flipper Application Manifests (.fam) {#app_manifests}
All components of Flipper Zero firmware — services, user applications, and system settings — are developed independently. Each component has a build system manifest file named `application.fam`, which defines the basic properties of that component and its relations to other parts of the system.
When building firmware, **`fbt`** collects all application manifests and processes their dependencies. Then it builds only those components referenced in the current build configuration. See [FBT docs](./fbt.md#firmware-application-set) for details on build configurations.
When building firmware, `fbt` collects all application manifests and processes their dependencies. Then it builds only those components referenced in the current build configuration. See [FBT docs](fbt.md) for details on build configurations.
## Application definition
A firmware component's properties are declared in a Python code snippet, forming a call to the `App()` function with various parameters.
Only two parameters are mandatory: **_appid_** and **_apptype_**. Others are optional and may only be meaningful for certain application types.
Only two parameters are mandatory: **appid** and **apptype**. Others are optional and may only be meaningful for certain application types.
### Parameters
@@ -34,7 +34,7 @@ Only two parameters are mandatory: **_appid_** and **_apptype_**. Others are opt
- **flags**: internal flags for system apps. Do not use.
- **cdefines**: C preprocessor definitions to declare globally for other apps when the current application is included in the active build configuration. **For external applications**: specified definitions are used when building the application itself.
- **requires**: list of application IDs to include in the build configuration when the current application is referenced in the list of applications to build.
- **conflicts**: list of application IDs with which the current application conflicts. If any of them is found in the constructed application list, **`fbt`** will abort the firmware build process.
- **conflicts**: list of application IDs with which the current application conflicts. If any of them is found in the constructed application list, `fbt` will abort the firmware build process.
- **provides**: functionally identical to **_requires_** field.
- **stack_size**: stack size in bytes to allocate for an application on its startup. Note that allocating a stack too small for an app to run will cause a system crash due to stack overflow, and allocating too much stack space will reduce usable heap memory size for apps to process data. _Note: you can use `ps` and `free` CLI commands to profile your app's memory usage._
- **icon**: animated icon name from built-in assets to be used when building the app as a part of the firmware.
@@ -55,11 +55,11 @@ The following parameters are used only for [FAPs](./AppsOnSDCard.md):
- **fap_description**: string, may be empty. Short application description.
- **fap_author**: string, may be empty. Application's author.
- **fap_weburl**: string, may be empty. Application's homepage.
- **fap_icon_assets**: string. If present, it defines a folder name to be used for gathering image assets for this application. These images will be preprocessed and built alongside the application. See [FAP assets](./AppsOnSDCard.md#fap-assets) for details.
- **fap_extbuild**: provides support for parts of application sources to be built by external tools. Contains a list of `ExtFile(path="file name", command="shell command")` definitions. **`fbt`** will run the specified command for each file in the list.
- **fap_icon_assets**: string. If present, it defines a folder name to be used for gathering image assets for this application. These images will be preprocessed and built alongside the application. See [FAP assets](AppsOnSDCard.md) for details.
- **fap_extbuild**: provides support for parts of application sources to be built by external tools. Contains a list of `ExtFile(path="file name", command="shell command")` definitions. `fbt` will run the specified command for each file in the list.
- **fal_embedded**: boolean, default `False`. Applies only to PLUGIN type. If `True`, the plugin will be embedded into host application's .fap file as a resource and extracted to `apps_assets/APPID` folder on its start. This allows plugins to be distributed as a part of the host application.
Note that commands are executed at the firmware root folder, and all intermediate files must be placed in an application's temporary build folder. For that, you can use pattern expansion by **`fbt`**: `${FAP_WORK_DIR}` will be replaced with the path to the application's temporary build folder, and `${FAP_SRC_DIR}` will be replaced with the path to the application's source folder. You can also use other variables defined internally by **`fbt`**.
Note that commands are executed at the firmware root folder, and all intermediate files must be placed in an application's temporary build folder. For that, you can use pattern expansion by `fbt`: `${FAP_WORK_DIR}` will be replaced with the path to the application's temporary build folder, and `${FAP_SRC_DIR}` will be replaced with the path to the application's source folder. You can also use other variables defined internally by `fbt`.
Example for building an app from Rust sources:
@@ -77,12 +77,12 @@ Example for building an app from Rust sources:
Library sources must be placed in a subfolder of the `lib` folder within the application's source folder.
Each library is defined as a call to the `Lib()` function, accepting the following parameters:
- **name**: name of the library's folder. Required.
- **fap_include_paths**: list of the library's relative paths to add to the parent fap's include path list. The default value is `["."]`, meaning the library's source root.
- **sources**: list of filename masks to be used for gathering include files for this library. Paths are relative to the library's source root. The default value is `["*.c*"]`.
- **cflags**: list of additional compiler flags to be used for building this library. The default value is `[]`.
- **cdefines**: list of additional preprocessor definitions to be used for building this library. The default value is `[]`.
- **cincludes**: list of additional include paths to be used for building this library. Paths are relative to the application's root. This can be used for providing external search paths for this library's code — for configuration headers. The default value is `[]`.
- **name**: name of the library's folder. Required.
- **fap_include_paths**: list of the library's relative paths to add to the parent fap's include path list. The default value is `["."]`, meaning the library's source root.
- **sources**: list of filename masks to be used for gathering include files for this library. Paths are relative to the library's source root. The default value is `["*.c*"]`.
- **cflags**: list of additional compiler flags to be used for building this library. The default value is `[]`.
- **cdefines**: list of additional preprocessor definitions to be used for building this library. The default value is `[]`.
- **cincludes**: list of additional include paths to be used for building this library. Paths are relative to the application's root. This can be used for providing external search paths for this library's code — for configuration headers. The default value is `[]`.
Example for building an app with a private library:
@@ -105,12 +105,12 @@ Example for building an app with a private library:
],
```
For that snippet, **`fbt`** will build 2 libraries: one from sources in `lib/mbedtls` folder and another from sources in the `lib/loclass` folder. For the `mbedtls` library, **`fbt`** will add `lib/mbedtls/include` to the list of include paths for the application and compile only the files specified in the `sources` list. Additionally, **`fbt`** will enable `MBEDTLS_ERROR_C` preprocessor definition for `mbedtls` sources.
For the `loclass` library, **`fbt`** will add `lib/loclass` to the list of the include paths for the application and build all sources in that folder. Also, **`fbt`** will disable treating compiler warnings as errors for the `loclass` library, which can be useful when compiling large 3rd-party codebases.
For that snippet, `fbt` will build 2 libraries: one from sources in `lib/mbedtls` folder and another from sources in the `lib/loclass` folder. For the `mbedtls` library, `fbt` will add `lib/mbedtls/include` to the list of include paths for the application and compile only the files specified in the `sources` list. Additionally, `fbt` will enable `MBEDTLS_ERROR_C` preprocessor definition for `mbedtls` sources.
For the `loclass` library, `fbt` will add `lib/loclass` to the list of the include paths for the application and build all sources in that folder. Also, `fbt` will disable treating compiler warnings as errors for the `loclass` library, which can be useful when compiling large 3rd-party codebases.
Both libraries will be linked with the application.
## `.fam` file contents
## .fam file contents
The `.fam` file contains one or more application definitions. For example, here's a part of `applications/service/bt/application.fam`:

28
documentation/AppsOnSDCard.md
View File

@@ -1,4 +1,4 @@
# FAP (Flipper Application Package)
# FAP (Flipper Application Package) {#apps_on_sd_card}
[fbt](./fbt.md) supports building applications as FAP files. FAPs are essentially `.elf` executables with extra metadata and resources bundled in.
@@ -6,7 +6,7 @@ FAPs are built with the `faps` target. They can also be deployed to the `dist` f
FAPs do not depend on being run on a specific firmware version. Compatibility is determined by the FAP's metadata, which includes the required [API version](#api-versioning).
## How to set up an application to be built as a FAP
## How to set up an application to be built as a FAP {#fap-howto}
FAPs are created and developed the same way as internal applications that are part of the firmware.
@@ -21,15 +21,15 @@ To build your application as a FAP, create a folder with your app's source code
FAPs can include static and animated images as private assets. They will be automatically compiled alongside application sources and can be referenced the same way as assets from the main firmware.
To use that feature, put your images in a subfolder inside your application's folder, then reference that folder in your application's manifest in the `fap_icon_assets` field. See [Application Manifests](./AppManifests.md#application-definition) for more details.
To use that feature, put your images in a subfolder inside your application's folder, then reference that folder in your application's manifest in the `fap_icon_assets` field. See [Application Manifests](AppManifests.md) for more details.
To use these assets in your application, put `#include "{APPID}_icons.h"` in your application's source code, where `{APPID}` is the `appid` value field from your application's manifest. Then you can use all icons from your application's assets the same way as if they were a part of `assets_icons.h` of the main firmware.
Images and animated icons should follow the same [naming convention](../assets/ReadMe.md#asset-naming-rules) as those from the main firmware.
Images and animated icons should follow the same [naming convention](../assets/ReadMe.md) as those from the main firmware.
## Debugging FAPs
**`fbt`** includes a script for gdb-py to provide debugging support for FAPs, `debug/flipperapps.py`. It is loaded in default debugging configurations by **`fbt`** and stock VS Code configurations.
`fbt` includes a script for gdb-py to provide debugging support for FAPs, `debug/flipperapps.py`. It is loaded in default debugging configurations by `fbt` and stock VS Code configurations.
With it, you can debug FAPs as if they were a part of the main firmware — inspect variables, set breakpoints, step through the code, etc.
@@ -43,7 +43,7 @@ To debug FAPs, do the following:
1. Build firmware with `./fbt`
2. Flash it with `./fbt flash`
3. [Build your FAP](#how-to-set-up-an-application-to-be-built-as-a-fap) and run it on Flipper
3. [Build your FAP](#fap-howto) and run it on Flipper
After that, you can attach with `./fbt debug` or VS Code and use all debug features.
@@ -59,25 +59,25 @@ Applications are built for a specific API version. It is a part of the hardware
The App Loader allocates memory for the application and copies it to RAM, processing relocations and providing concrete addresses for imported symbols using the [symbol table](#symbol-table). Then it starts the application.
## API versioning
## API versioning {#api-versioning}
Not all parts of firmware are available for external applications. A subset of available functions and variables is defined in the "api_symbols.csv" file, which is a part of the firmware target definition in the `targets/` directory.
**`fbt`** uses semantic versioning for the API. The major version is incremented when there are breaking changes in the API. The minor version is incremented when new features are added.
`fbt` uses semantic versioning for the API. The major version is incremented when there are breaking changes in the API. The minor version is incremented when new features are added.
Breaking changes include:
- Removing a function or a global variable
- Changing the signature of a function
API versioning is mostly automated by **`fbt`**. When rebuilding the firmware, **`fbt`** checks if there are any changes in the API exposed by headers gathered from `SDK_HEADERS`. If so, it stops the build, adjusts the API version, and asks the user to go through the changes in the `.csv` file. New entries are marked with a "`?`" mark, and the user is supposed to change the mark to "`+`" for the entry to be exposed for FAPs, or to "`-`" for it to be unavailable.
API versioning is mostly automated by `fbt`. When rebuilding the firmware, `fbt` checks if there are any changes in the API exposed by headers gathered from `SDK_HEADERS`. If so, it stops the build, adjusts the API version, and asks the user to go through the changes in the `.csv` file. New entries are marked with a "`?`" mark, and the user is supposed to change the mark to "`+`" for the entry to be exposed for FAPs, or to "`-`" for it to be unavailable.
**`fbt`** will not allow building a firmware until all "`?`" entries are changed to "`+`" or "`-`".
`fbt` will not allow building a firmware until all "`?`" entries are changed to "`+`" or "`-`".
**NB:** **`fbt`** automatically manages the API version. The only case where manually incrementing the major API version is allowed (and required) is when existing "`+`" entries are to be changed to "`-`".
**NB:** `fbt` automatically manages the API version. The only case where manually incrementing the major API version is allowed (and required) is when existing "`+`" entries are to be changed to "`-`".
### Symbol table
### Symbol table {#symbol-table}
The symbol table is a list of symbols exported by firmware and available for external applications. It is generated by **`fbt`** from the API symbols file and is used by the App Loader to resolve addresses of imported symbols. It is build as a part of the `fap_loader` application.
The symbol table is a list of symbols exported by firmware and available for external applications. It is generated by `fbt` from the API symbols file and is used by the App Loader to resolve addresses of imported symbols. It is build as a part of the `fap_loader` application.
**`fbt`** also checks if all imported symbols are present in the symbol table. If there are any missing symbols, it will issue a warning listing them. The application won't be able to run on the device until all required symbols are provided in the symbol table.
`fbt` also checks if all imported symbols are present in the symbol table. If there are any missing symbols, it will issue a warning listing them. The application won't be able to run on the device until all required symbols are provided in the symbol table.

2
documentation/ExpansionModules.md
View File

@@ -1,4 +1,4 @@
# Expansion Module Protocol - Draft
# Expansion Module Protocol {#expansion_protocol}
## Terms and definitions

2
documentation/FuriCheck.md
View File

@@ -1,4 +1,4 @@
# Run time checks and forced system crash
# Run time checks and forced system crash {#furi_check}
The best way to protect system integrity is to reduce amount cases that we must handle and crash the system as early as possible.
For that purpose we have bunch of helpers located in Furi Core check.h.

2
documentation/FuriHalBus.md
View File

@@ -1,4 +1,4 @@
# Using FuriHalBus API
# Using FuriHalBus API {#furi_hal_bus}
## Basic info

2
documentation/FuriHalDebuging.md
View File

@@ -1,4 +1,4 @@
# Furi HAL Debugging
# Furi HAL Debugging {#furi_hal_debugging}
Some Furi subsystems got additional debugging features that can be enabled by adding additional defines to firmware compilation.
Usually they are used for low level tracing and profiling or signal redirection/duplication.

4
documentation/HardwareTargets.md
View File

@@ -1,4 +1,4 @@
## What a Firmware Target is
## What a Firmware Target is {#hardware_targets}
Flipper's firmware is modular and supports different hardware configurations in a common code base. It encapsulates hardware-specific differences in `furi_hal`, board initialization code, linker files, SDK data and other information in a _target definition_.
@@ -29,7 +29,7 @@ A target definition file, `target.json`, is a JSON file that can contain the fol
Not all applications are available on different hardware targets.
* For applications built into the firmware, you have to specify a compatible application set using `FIRMWARE_APP_SET=...` fbt option. See [fbt docs](./fbt.md#firmware-application-set) for details on build configurations.
* For applications built into the firmware, you have to specify a compatible application set using `FIRMWARE_APP_SET=...` fbt option. See [fbt docs](./fbt.md) for details on build configurations.
* For applications built as external .faps, you have to explicitly specify compatible targets in application's manifest, `application.fam`. For example, to limit application to a single target, add `targets=["f7"],` to the manifest. It won't be built for other targets.

2
documentation/KeyCombo.md
View File

@@ -1,4 +1,4 @@
# Key Combos
# Key Combos {#key_combos}
There are times when your Flipper feels blue and doesn't respond to any of your commands due to a software issue. This guide will help you solve this problem.

2
documentation/LFRFIDRaw.md
View File

@@ -1,4 +1,4 @@
# Reading RAW RFID data
# Reading RAW RFID data {#lfrfid_raw}
Flipper Zero has the option to read RAW data from 125 kHz cards that allows you to record the card's data and save it, similar to how a dictaphone records sound.

30
documentation/OTA.md
View File

@@ -1,20 +1,22 @@
# Executing code from RAM
# Flipper Zero OTA update process {#ota_updates}
## Executing code from RAM
In Flipper firmware, we have a special boot mode that loads a specially crafted system image into RAM and transfers control to it. System image executing in RAM has full write access to Flipper's entire flash memory — something that's not possible when running main code from the same flash.
We leverage that boot mode to perform OTA firmware updates, including operations on a radio stack running on the second MCU core.
# How does Flipper OTA work?
## How does Flipper OTA work?
Installation of OTA updates goes through 3 stages:
## 1. Backing up internal storage (`/int`)
### 1. Backing up internal storage (/int)
It is a special partition of Flipper's flash memory, taking up all available space not used by the firmware code. Newer versions of firmware may be of different size, and simply installing them would cause flash repartitioning and data loss.
So, before taking any action on the firmware, we back up the current configuration from `/int` into a plain tar archive on the SD card.
## 2. Performing device update
### 2. Performing device update
The main firmware loads an updater image — a customized build of the main Flipper firmware — into RAM and runs it. Updater performs operations on system flash as described by an Update manifest file.
@@ -24,17 +26,17 @@ Then, updater validates and corrects Option Bytes — a special memory region co
After that, updater loads a `.dfu` file with firmware to be flashed, checks its integrity using CRC32, writes it to system flash and validates written data.
## 3. Restoring internal storage and updating resources
### 3. Restoring internal storage and updating resources
After performing operations on flash memory, the system restarts into newly flashed firmware. Then it performs restoration of previously backed up `/int` contents.
If the update package contains an additional resources archive, it is extracted onto the SD card.
# Update manifest
## Update manifest
An update package comes with a manifest that contains a description of its contents. The manifest is in Flipper File Format — a simple text file, comprised of key-value pairs.
## Mandatory fields
### Mandatory fields
An update manifest must contain the following keys in the given order:
@@ -50,7 +52,7 @@ An update manifest must contain the following keys in the given order:
- **Loader CRC**: CRC32 of loader file. Note that it is represented in little-endian hex.
## Optional fields
### Optional fields
Other fields may have empty values. In this case, updater skips all operations related to these values.
@@ -66,7 +68,7 @@ Other fields may have empty values. In this case, updater skips all operations r
- **OB reference**, **OB mask**, **OB write mask**: reference values for validating and correcting option bytes.
# OTA update error codes
## OTA update error codes
We designed the OTA update process to be as fail-safe as possible. We don't start any risky operations before validating all related pieces of data to ensure we don't leave the device in a partially updated, or bricked, state.
@@ -102,21 +104,21 @@ Even if something goes wrong, updater allows you to retry failed operations and
| Restoring LFS | **12** | **0-100** | FS read/write error |
| Updating resources | **13** | **0-100** | SD card read/write error |
# Building update packages
## Building update packages
## Full package
### Full package
To build a full update package, including firmware, radio stack and resources for the SD card, run:
`./fbt COMPACT=1 DEBUG=0 updater_package`
## Minimal package
### Minimal package
To build a minimal update package, including only firmware, run:
`./fbt COMPACT=1 DEBUG=0 updater_minpackage`
## Customizing update bundles
### Customizing update bundles
Default update packages are built with Bluetooth Light stack.
You can pick a different stack if your firmware version supports it, and build a bundle with it by passing the stack type and binary name to `fbt`:
@@ -127,7 +129,7 @@ Note that `COPRO_OB_DATA` must point to a valid file in the `scripts` folder con
In certain cases, you might have to confirm your intentions by adding `COPRO_DISCLAIMER=...` to the build command line.
## Building partial update packages
### Building partial update packages
You can customize package contents by calling `scripts/update.py` directly.
For example, to build a package only for installing BLE FULL stack:

14
documentation/UnitTests.md
View File

@@ -1,11 +1,11 @@
# Unit tests
# Unit tests {#unit_tests}
## Intro
Unit tests are special pieces of code that apply known inputs to the feature code and check the results to see if they are correct.
They are crucial for writing robust, bug-free code.
Flipper Zero firmware includes a separate application called [unit_tests](/applications/debug/unit_tests).
Flipper Zero firmware includes a separate application called [unit_tests](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests).
It is run directly on Flipper devices in order to employ their hardware features and rule out any platform-related differences.
When contributing code to the Flipper Zero firmware, it is highly desirable to supply unit tests along with the proposed features.
@@ -20,7 +20,7 @@ To run the unit tests, follow these steps:
3. Launch the CLI session and run the `unit_tests` command.
**NOTE:** To run a particular test (and skip all others), specify its name as the command argument.
See [test_index.c](/applications/debug/unit_tests/test_index.c) for the complete list of test names.
See [test_index.c](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/applications/debug/unit_tests/test_index.c) for the complete list of test names.
## Adding unit tests
@@ -28,11 +28,11 @@ See [test_index.c](/applications/debug/unit_tests/test_index.c) for the complete
#### Entry point
The common entry point for all tests is the [unit_tests](/applications/debug/unit_tests) application. Test-specific code is placed into an arbitrarily named subdirectory and is then called from the [test_index.c](/applications/debug/unit_tests/test_index.c) source file.
The common entry point for all tests is the [unit_tests](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests) application. Test-specific code is placed into an arbitrarily named subdirectory and is then called from the [test_index.c](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests/test_index.c) source file.
#### Test assets
Some unit tests require external data in order to function. These files (commonly called assets) reside in the [unit_tests](/applications/debug/unit_tests/resources/unit_tests) directory in their respective subdirectories. Asset files can be of any type (plain text, FlipperFormat (FFF), binary, etc.).
Some unit tests require external data in order to function. These files (commonly called assets) reside in the [unit_tests](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests/resources/unit_tests) directory in their respective subdirectories. Asset files can be of any type (plain text, FlipperFormat (FFF), binary, etc.).
### Application-specific
@@ -41,9 +41,9 @@ Some unit tests require external data in order to function. These files (commonl
Each infrared protocol has a corresponding set of unit tests, so it makes sense to implement one when adding support for a new protocol.
To add unit tests for your protocol, follow these steps:
1. Create a file named `test_<your_protocol_name>.irtest` in the [assets](/applications/debug/unit_tests/resources/unit_tests/infrared) directory.
1. Create a file named `test_<your_protocol_name>.irtest` in the [assets](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests/resources/unit_tests/infrared) directory.
2. Fill it with the test data (more on it below).
3. Add the test code to [infrared_test.c](/applications/debug/unit_tests/infrared/infrared_test.c).
3. Add the test code to [infrared_test.c](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/applications/debug/unit_tests/infrared/infrared_test.c).
4. Build and install firmware with resources, install it on your Flipper and run the tests to see if they pass.
##### Test data format

76
documentation/UniversalRemotes.md Normal file
View File

@@ -0,0 +1,76 @@
# Universal Remotes {#universal_remotes}
## Televisions
Adding your TV set to the universal remote is quite straightforward. Up to 6 signals can be recorded: `Power`, `Mute`, `Vol_up`, `Vol_dn`, `Ch_next`, and `Ch_prev`. Any of them can be omitted if not supported by your TV.
Each signal is recorded using the following algorithm:
1. Get the remote and point it to Flipper's IR receiver.
2. Start learning a new remote if it's the first button or press `+` to add a new button otherwise.
3. Press a remote button and save it under a corresponding name.
4. Repeat steps 2-3 until all required signals are saved.
The signal names are self-explanatory. Remember to make sure that every recorded signal does what it's supposed to.
If everything checks out, append these signals **to the end** of the [TV universal remote file](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/applications/main/infrared/resources/infrared/assets/tv.ir).
## Audio players
Adding your audio player to the universal remote is done in the same manner as described above. Up to 8 signals can be recorded: `Power`, `Play`, `Pause`, `Vol_up`, `Vol_dn`, `Next`, `Prev`, and `Mute`. Any of them can be omitted if not supported by the player.
The signal names are self-explanatory.
On many remotes, the `Play` button doubles as `Pause`. In this case, record it as `Play` omitting the `Pause`.
Make sure that every signal does what it's supposed to.
If everything checks out, append these signals **to the end** of the [audio player universal remote file](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/applications/main/infrared/resources/infrared/assets/audio.ir).
## Projectors
Adding your projector to the universal remote is really simple. Up to 4 signals can be recorded: `Power`, `Mute`, `Vol_up`, `Vol_dn`. Any of them can be omitted if not supported by your projector.
To save time, please make sure every recording has been named accordingly.
In case of omitting, on most projectors with the 4 following buttons, you should not have a problem.
## Air conditioners
Air conditioners differ from most other infrared-controlled devices because their state is tracked by the remote.
The majority of A/C remotes have a small display that shows the current mode, temperature, and other settings.
When the user presses a button, a whole set of parameters is transmitted to the device, which must be recorded and used as a whole.
In order to add a particular air conditioner to the universal remote, 6 signals must be recorded: `Off`, `Dh`, `Cool_hi`, `Cool_lo`, `Heat_hi`, and `Heat_lo`.
Each signal (except `Off`) is recorded using the following algorithm:
1. Get the remote and press the **Power Button** so that the display shows that A/C is ON.
2. Set the A/C to the corresponding mode (see table below), leaving other parameters such as fan speed or vane on **AUTO** (if applicable).
3. Press the **POWER** button to switch the A/C off.
4. Start learning a new remote on Flipper if it's the first button or press `+` to add a new button otherwise.
5. Point the remote to Flipper's IR receiver as directed and press **POWER** button once again.
6. Save the resulting signal under the specified name.
7. Repeat steps 2-6 for each signal from the table below.
| Signal | Mode | Temperature | Note |
| :-----: | :--------: | :---------: | ----------------------------------- |
| Dh | Dehumidify | N/A | |
| Cool_hi | Cooling | See note | Lowest temperature in cooling mode |
| Cool_lo | Cooling | 23°C | |
| Heat_hi | Heating | See note | Highest temperature in heating mode |
| Heat_lo | Heating | 23°C | |
Finally, record the `Off` signal:
1. Make sure the display shows that the A/C is ON.
2. Start learning a new signal on Flipper and point the remote towards the IR receiver.
3. Press the **POWER** button so that the remote shows the OFF state.
4. Save the resulting signal under the name `Off`.
The resulting remote file should now contain 6 signals. You can omit any of them, but you then won't be able to use their functionality.
Test the file against the actual device. Make sure that every signal does what it's supposed to.
If everything checks out, append these signals **to the end** of the [A/C universal remote file](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/applications/main/infrared/resources/infrared/assets/ac.ir).
## Final steps
The order of signals is not important, but they should be preceded by the following comment: `# Model: <Your model name>` in order to keep the library organized.
When done, open a pull request containing the changed file.

246
documentation/devboard/Firmware update on Developer Board.md Normal file
View File

@@ -0,0 +1,246 @@
# Firmware update on Developer Board {#dev_board_fw_update}
It's important to regularly update your Developer Board to keep it up to date. This tutorial will guide you through the necessary steps to successfully update the firmware of your Developer Board.
This tutorial assumes that you're familiar with the basics of the command line. If you’re unfamiliar with the command line, please refer to the [Windows](https://www.digitalcitizen.life/command-prompt-how-use-basic-commands/) or [MacOS/Linux](https://ubuntu.com/tutorials/command-line-for-beginners#1-overview) command line tutorials.
***
## Downloading the latest firmware
The first thing you need to do is to download the latest Developer Board firmware.
To get the latest pre-built firmware, do the following:
1. Go to the [Update Server page](https://update.flipperzero.one/builds/blackmagic-firmware).
![The Update Server page hosts different versions of the Developer Board firmware](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/gIXVO9VrE4LK05CmcMSSD_monosnap-miro-2023-07-19-17-36-23.jpg)
There, you can find the following version of the Developer Board firmware:
* **Release:** The most stable version of the firmware, which went through rigorous testing. The Release firmware version has the following format: **X.Y.Z/**, where X, Y, and Z are the build numbers. We recommend installing this version of the firmware.
* **Release-candidate:** The firmware version that hasn't been tested yet and may contain bugs. The Release-candidate firmware version has the following format: **X.Y.Z-rc/**, where X, Y, and Z are the build numbers.
* **Development:** The firmware version which builds every day and contains the latest features but might be unstable.
2. Open the folder with the latest Release firmware and download the `blackmagic-firmware-s2-full-X.Y.Z.tgz` file.
***
## Extracting the firmware
After downloading the firmware archive, extract it into a folder:
* On Windows, you can use any archive manager for this, for example, [7-Zip](https://www.7-zip.org/).
* On MacOS and Linux, you can use the `tar` command:
```text
tar -xzf blackmagic-firmware-s2-full-X.Y.Z.tgz -C <destination_directory>
```
Don't forget to replace `X.Y.Z` with the actual version number and set the destination directory!
***
## Installing the prerequisites for flashing
Install the tools below if you haven't already.
### Python
Download and install [Python3](https://www.python.org/downloads/). Make sure to check the “Add Python to PATH” option during installation.
### pip
To install the pip package manager, run the following command in the Terminal:
```text
python3 -m ensurepip --upgrade
```
If this command fails, please refer to the [official pip documentation](https://pip.pypa.io/en/stable/installation/) for alternative installation methods.
### esptool
esptool is a command-line utility for flashing ESP8266 and ESP32 microcontrollers, including the ESP32-S2 in your Developer Board.
To install esptool, run the following command in the Terminal:
```text
pip3 install esptool
```
If this command fails, try using **pip** instead of **pip3**. If this didn’t help, please refer to the [official esptool installation manual](https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html).
***
## Connecting the Developer Board to your computer
1. List all of the serial devices on your computer.
* ***Windows***
On Windows, go to Device Manager and expand the Ports (COM & LPT) section.
* ***macOS***
On macOS, you can run the following command in the Terminal:
```text
ls /dev/cu.*
```
* ***Linux***
On Linux, you can run the following command in the Terminal:
```text
ls /dev/tty*
```
View the devices in the list.
2. Connect the Developer Board to your computer using a USB-C cable.\
![The Developer Board in Wired mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/Aq7gfMI-m_5H6sGGjwb4I_monosnap-miro-2023-07-19-19-47-39.jpg)
3. Switch your Developer Board to Bootloader mode:
3.1. Press and hold the **BOOT** button.
3.2. Press the **RESET** button while holding the **BOOT** button.
3.3. Release the **BOOT** button.
![You can easily switch the Dev Board to Bootloader mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/KynP9iT6sJ3mXLaLyI82__image.png)
4. Repeat Step 1 and view the name of your Developer Board that appeared in the list.
For example, on macOS:
```text
/dev/cu.usbmodem01
```
***
## Flashing the firmware
### Getting the flash command
1. Run the Terminal and navigate to the folder with the extracted firmware.
2. Run the following command to read the file with the flash command:
```text
cat flash.command
```
If you see a similar output, you can proceed to the Flashing step:
```text
esptool.py -p (PORT) -b 460800 --before default_reset --after hard_reset --chip esp32s2 write_flash --flash_mode dio --flash_freq 80m --flash_size 4MB 0x1000 bootloader.bin 0x10000 blackmagic.bin 0x8000 partition-table.bin
```
Don't use the exact command above for your Developer Board in the next step since it's just an example and may not match your firmware version!
If you get an error, ensure you’re in the correct directory and extracted the firmware archive correctly.
***
### Flashing
1. Copy the command you got from the previous step and replace the `(PORT)` part with the name of the serial device you learned earlier.
For Windows, replace `(PORT)` with the COM port number—for example, `COM3`.
2. Run the command in the Terminal.
Your command should look similar to this:
```text
esptool.py -p /dev/cu.usbmodem01 -b 460800 --before default_reset --after hard_reset --chip esp32s2 write_flash --flash_mode dio --flash_freq 80m --flash_size 4MB 0x1000 bootloader.bin 0x10000 blackmagic.bin 0x8000 partition-table.bin
```
If you get an error, ensure that you’ve entered the correct serial device name and that the Developer Board is in Bootloader mode.
3. Wait till the firmware flashing is over. The flashing process takes about 30 seconds.
The Terminal output should look similar to this:
```text
esptool.py v4.6.1
Serial port /dev/cu.usbmodem01
Connecting...
Chip is ESP32-S2 (revision v0.0)
Features: WiFi, No Embedded Flash, No Embedded PSRAM, ADC and temperature sensor
calibration in BLK2 of efuse V2
Crystal is 40MHz
MAC: 00:11:22:33:44:55
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
Changed.
Configuring flash size...
Flash will be erased from 0x00001000 to 0x00004fff...
Flash will be erased from 0x00010000 to 0x000ecfff...
Flash will be erased from 0x00008000 to 0x00008fff...
Compressed 13248 bytes to 9298...
Wrote 13248 bytes (9298 compressed) at 0x00001000 in 0.3 seconds (effective 402.7 kbit/s)...
Hash of data verified.
Compressed 904288 bytes to 562550...
Wrote 904288 bytes (562550 compressed) at 0x00010000 in 6.7 seconds (effective 1076.5 kbit/s)...
Hash of data verified.
Compressed 3072 bytes to 124...
Wrote 3072 bytes (124 compressed) at 0x00008000 in 0.1 seconds (effective 360.8 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
```
If the Terminal output has these two lines at the end, your Developer Board has been successfully updated:
```text
Leaving...
Hard resetting via RTS pin...
```
If you get this warning, you can safely ignore it:
```text
WARNING: ESP32-S2 (revision v0.0) chip was placed into download mode using GPIO0.
esptool.py can not exit the download mode over USB. To run the app, reset the chip manually.
To suppress this note, set --after option to 'no_reset
```
#### If flashing failed
If you get an error message during the flashing process, such as:
```text
A fatal error occurred: Serial data stream stopped: Possible serial noise or corruption.
```
or
```text
FileNotFoundError: [Errno 2] No such file or directory: '/dev/cu.usbmodem01'
```
Try doing the following:
* Disconnect the Developer Board from your computer, then reconnect it.
* Use a different USB port on your computer.
* Use a different USB-C cable.
***
## Finishing the installation
After flashing the firmware, you can reboot the Developer Board by pressing the **RESET** button.
![Reset the Developer Board](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/rcQeKARgrVwa51tLoo-qY_monosnap-miro-2023-07-20-18-29-33.jpg)
The Developer Board should appear as a serial device on your computer. Now, you can use it with the Black Magic Debug client of your choice.

175
documentation/devboard/Get started with the Dev Board.md Normal file
View File

@@ -0,0 +1,175 @@
# Get started with the Dev Board {#dev_board_get_started}
The Wi-Fi Developer Board serves as a tool to debug the Flipper Zero firmware. To debug the firmware, the initial step involves compiling the firmware from its source code. This process enables the debugging functionality within the firmware and generates all the necessary files required for debugging purposes.
> **NOTE:** Building and debugging the Flipper Zero firmware is fully supported on MacOS and Linux. Support for Windows is in beta test.
***
## Updating the firmware of your Developer Board
Update the firmware of your Developer Board before using it. For more information, visit [Firmware update on Developer Board](https://docs.flipperzero.one/development/hardware/wifi-debugger-module/update).
***
## Installing Git
You’ll need Git installed on your computer to clone the firmware repository. If you don’t have Git, install it by doing the following:
* **MacOS**
On MacOS, install the **Xcode Command Line Tools** package, which includes Git as one of the pre-installed command-line utilities, by running in the Terminal the following command:
```text
xcode-select --install
```
* **Linux**
On Linux, you can install Git using your package manager. For example, on Ubuntu, run in the Terminal the following command:
```text
sudo apt install git
```
For other distributions, refer to your package manager documentation.
***
## Building the firmware
First, clone the firmware repository:
```text
git clone --recursive https://github.com/flipperdevices/flipperzero-firmware.git
cd flipperzero-firmware
```
Then, run the **Flipper Build Tool** (FBT) to build the firmware:
```text
./fbt
```
***
## Connecting the Developer Board
The Developer Board can work in the **Wired** mode and two **Wireless** modes: **Wi-Fi access point (AP)** mode and **Wi-Fi client (STA)** mode. The Wired mode is the simplest to set up, but requires a USB Type-C cable. The Wireless modes are more complex to set up, but they allow you to debug your Flipper Zero wirelessly.
> **NOTE:** Use the following credentials when connecting to the Developer Board in **Wi-Fi access point** mode: Name: **blackmagic**, Password: **iamwitcher**
## Wired
![The Developer Board in Wired mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/jZdVlRTPVdSQVegzCyXp7_monosnap-miro-2023-06-22-16-28-06.jpg)
To connect the Developer Board in **Wired** mode, do the following:
1. Cold-plug the Developer Board by turning off your Flipper Zero and connecting the Developer Board, and then turning it back on.
2. On your computer, open the **Terminal** and run the following:
* **MacOS**
```text
ls /dev/cu.*
```
* **Linux**
```text
ls /dev/tty*
```
Note the list of devices.
3. Connect the Developer Board to your computer via a USB-C cable.
4. Rerun the command. Two new devices have to appear: this is the Developer Board.
> **NOTE:** If the Developer Board doesn’t appear in the list of devices, try using a different cable, USB port, or computer.
>
> **NOTE:** Flipper Zero logs can only be viewed when the Developer Board is connected via USB. The option to view logs over Wi-Fi will be added in future updates. For more information, visit [Reading logs via the Dev Board](https://docs.flipperzero.one/development/hardware/wifi-debugger-module/reading-logs).
## Wireless
### Wi-Fi access point (AP) mode
![The Developer Board in Wi-Fi access point mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/tKRTMHAuruiLSEce2a8Ve_monosnap-miro-2023-06-22-16-39-17.jpg)
Out of the box, the Developer Board is configured to work as a **Wi-Fi access point**. This means it will create its own Wi-Fi network to which you can connect. If your Developer Board doesn’t create a Wi-Fi network, it is probably configured to work in **Wi-Fi client** mode. To reset your Developer Board back to **Wi-Fi access point** mode, press and hold the **BOOT** button for 10 seconds, then wait for the module to reboot.
![You can reconfigure the Developer Board mode by pressing and holding the BOOT button](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/57eELJsAwMxeZCEA1NMJw_monosnap-miro-2023-06-22-20-33-27.jpg)
To connect the Developer Board in **Wi-Fi access point** mode, do the following:
1. Cold-plug the Developer Board by turning off your Flipper Zero and connecting the Developer Board, and then turning it back on.
2. Open Wi-Fi settings on your client device (phone, laptop, or other).
3. Connect to the network:
* Name: **blackmagic**
* Password: **iamwitcher**
4. To configure the Developer Board, open a browser and go to `http://192.168.4.1`.
#### Wi-Fi client (STA) mode
![The Developer Board in Wi-Fi client mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/xLQpFyYPfUS5Cx0uQhrNd_monosnap-miro-2023-06-23-12-34-36.jpg)
To connect the Developer Board in **Wi-Fi client** mode, you need to configure it to connect to your Wi-Fi network by doing the following:
1. Cold-plug the Developer Board by turning off your Flipper Zero and connecting the Developer Board, and then turning it back on.
2. Connect to the Developer Board in **Wi-Fi access point** mode.
3. In a browser, go to the configuration page on `http://192.168.4.1`.
4. Select the **STA** mode and enter your network’s **SSID** (name) and **password**. For convenience, you can click the **+** button to see the list of nearby networks.
5. Save the configuration and reboot the Developer Board.
![In the Wi-Fi tab, you can set the Developer Board mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/klbLVj8lz2bEvm7j4wRaj_monosnap-miro-2023-06-23-13-06-32.jpg)
After rebooting, the Developer Board connects to your Wi-Fi network. You can connect to the device using the mDNS name [blackmagic.local](http://blackmagic.local) or the IP address it got from your router (you’ll have to figure this out yourself, every router is different).
After connecting to your debugger via [blackmagic.local](http://blackmagic.local), you can find its IP address in the **SYS** tab. You can also change the debugger’s mode to **AP** or **STA** there.
![In the SYS tab, you can view the IP address of your Developer Board](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/5XbUptlfqzlV0p6hRUqiG_monosnap-miro-2023-06-22-18-11-30.jpg)
***
## Debugging the firmware
Open the **Terminal** in the **flipperzero-firmware** directory that you cloned earlier and run the following command:
```text
./fbt flash_blackmagic
```
This will upload the firmware you’ve just built to your Flipper Zero via the Developer Board. After that, you can start debugging the firmware using the [GDB](https://www.gnu.org/software/gdb/) debugger. We recommend using **VSCode** with the recommended extensions, and we have pre-made configurations for it.
To debug in **VSCode**, do the following:
1. In VSCode, open the **flipperzero-firmware** directory.
2. You should see a notification about recommended extensions. Install them.
If there were no notifications, open the **Extensions** tab, enter `@recommended` in the search bar, and install the workspace recommendations.
3. In the **Terminal**, run the `./fbt vscode_dist` command. This will generate the VSCode configuration files needed for debugging.
4. In VSCode, open the **Run and Debug** tab and select **Attach FW (blackmagic)** from the dropdown menu.
5. If needed, flash your Flipper Zero with the `./fbt flash_blackmagic` command, then click the **Play** button in the debug sidebar to start the debugging session.
6. Note that starting a debug session halts the execution of the firmware, so you’ll need to click the **Continue** button on the toolbar at the top of your VSCode window to continue execution.
![Click Continue in the toolbar to continue execution of the firmware](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/lp8ygGaZ3DvWD3OSI9yGO_monosnap-miro-2023-06-23-17-58-09.jpg)
To learn about debugging, visit the following pages:
* [Debugging with GDB](https://sourceware.org/gdb/current/onlinedocs/gdb.pdf)
* [Debugging in VS Code](https://code.visualstudio.com/docs/editor/debugging)

152
documentation/devboard/Reading logs via the Dev Board.md Normal file
View File

@@ -0,0 +1,152 @@
# Reading logs via the Dev Board {#dev_board_reading_logs}
The Developer Board allows you to read Flipper Zero logs via UART. Unlike reading logs via the command-line interface (CLI), the Developer Board enables you to collect logs from the device directly to a serial console independently from the operating system of Flipper Zero. It allows you to see the device's logs when it's loading, updating, or crashing. It's useful for debugging and troubleshooting during software development.
> **NOTE:** Flipper Zero logs can only be viewed when the developer board is connected via USB. The option to view logs over Wi-Fi will be added in future updates.
## Setting the log level
Depending on your needs, you can set the log level by going to Main Menu -> Settings -> Log Level. To learn more about logging levels, visit [Settings](https://docs.flipperzero.one/basics/settings#d5TAt).
![You can manually set the preferred log level](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/INzQMw8QUsG9PXi30WFS0_monosnap-miro-2023-07-11-13-29-47.jpg)
***
## Viewing Flipper Zero logs
Depending on your operating system, you need to install an additional application on your computer to read logs via the Developer Board:
### MacOS
On MacOS, you need to install the **minicom** communication program by doing the following:
1. [Install Homebrew](https://brew.sh/) by running in the Terminal the following command:
```text
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
2. After installation of Homebrew, run the following command to install minicom:
```text
brew install minicom
```
After installation of minicom on your macOS computer, you can connect to the Developer Board to read Flipper Zero logs by doing the following:
1. Cold-plug the Developer Board into your Flipper Zero by turning off the Flipper Zero, connecting the developer board, and then turning it back on.
2. On your computer, open the Terminal and run the following command:
```text
ls /dev/cu.*
```
Note the list of devices.
3. Connect the developer board to your computer using a USB Type-C cable.\
![The Developer Board in Wired mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/iPpsMt2-is4aIjiVeFu5t_hjxs2i1oovrnps74v5jgsimage.png)
4. Rerun the command. Two new devices have to appear: this is the Developer Board.
```text
/dev/cu.usbmodemblackmagic1
/dev/cu.usbmodemblackmagic3
```
Your Developer Board might have different names.
5. Run the following command:
```text
minicom -D /dev/<port> -b 230400
```
Where `<port>` is the name of your device with a bigger number.
Example:
```text
minicom -D /dev/cu.usbmodemblackmagic3 -b 230400
```
6. View logs of your Flipper Zero in the Terminal.
7. To quit, close the minicom window or quit via the minicom menu.
### Linux
On Linux, you need to install the **minicom** communication program. For example, on Ubuntu, run in the Terminal the following command:
```text
sudo apt install minicom
```
After installation of minicom on your Linux computer, you can connect to the Developer Board to read Flipper Zero logs by doing the following:
1. Cold-plug the Developer Board into your Flipper Zero by turning off the Flipper Zero, connecting the developer board, and then turning it back on.
2. On your computer, open the Terminal and run the following command:
```text
ls /dev/tty*
```
Note the list of devices.
3. Connect the developer board to your computer using a USB Type-C cable.
![The Developer Board in Wired mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/iPpsMt2-is4aIjiVeFu5t_hjxs2i1oovrnps74v5jgsimage.png)
4. Rerun the command. Two new devices have to appear: this is the Developer Board.
```text
/dev/ttyACM0
/dev/ttyACM1
```
Your Developer Board might have different names.
5. Run the following command:
```text
minicom -D /dev/<port> \-b 230400
```
Where `<port>` is the name of your device with a bigger number.
Example:
```text
minicom -D /dev/ttyACM1 \-b 230400
```
6. View logs of your Flipper Zero in the Terminal.
> **NOTE:** If no logs are shown in the Terminal, try running the command from Step 5 with another device name.
7. To quit, close the minicom window or quit via the minicom menu.
### Windows
On Windows, do the following:
1. On your computer, [install the PuTTY application](https://www.chiark.greenend.org.uk/\~sgtatham/putty/latest.html).
2. Cold-plug the Developer Board into your Flipper Zero by turning off the Flipper Zero, connecting the developer board, and then turning it back on.
3. Connect the developer board to your computer using a USB Type-C cable.
![The Developer Board in Wired mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/iPpsMt2-is4aIjiVeFu5t_hjxs2i1oovrnps74v5jgsimage.png)
4. Find the serial port that the developer board is connected to by going to **Device Manager -> Ports (COM & LPT)** and looking for a new port that appears when you connect the Wi-Fi developer board.
![Go to Device Manager -> Ports (COM & LPT)](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/KKLQJK1lvqmI5iab3d__C_image.png)
5. Run the PuTTY application and select **Serial** as the connection type.
6. Enter the port number you found in the previous step into the **Serial line** field.
7. Set the **Speed** parameter to **230400** and click **Open**.
![Set the required parameters](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/ROBSJyfQ_CXiy4GUZcPbs_monosnap-miro-2023-07-12-13-56-47.jpg)
8. View logs of your Flipper Zero in the PuTTY terminal window.
9. To quit, close the PuTTY window.

10
documentation/fbt.md
View File

@@ -1,4 +1,4 @@
# Flipper Build Tool
# Flipper Build Tool {#fbt}
FBT is the entry point for firmware-related commands and utilities.
It is invoked by `./fbt` in the firmware project root directory. Internally, it is a wrapper around [scons](https://scons.org/) build system.
@@ -58,7 +58,7 @@ To use language servers other than the default VS Code C/C++ language server, us
## FBT targets
**`fbt`** keeps track of internal dependencies, so you only need to build the highest-level target you need, and **`fbt`** will make sure everything they depend on is up-to-date.
`fbt` keeps track of internal dependencies, so you only need to build the highest-level target you need, and `fbt` will make sure everything they depend on is up-to-date.
### High-level (what you most likely need)
@@ -83,8 +83,8 @@ To use language servers other than the default VS Code C/C++ language server, us
### Firmware targets
- `faps` - build all external & plugin apps as [`.faps`](./AppsOnSDCard.md#fap-flipper-application-package).
- **`fbt`** also defines per-app targets. For example, for an app with `appid=snake_game` target names are:
- `faps` - build all external & plugin apps as [`.faps`](AppsOnSDCard.md).
- `fbt` also defines per-app targets. For example, for an app with `appid=snake_game` target names are:
- `fap_snake_game`, etc. - build single app as `.fap` by its application ID.
- Check out [`--extra-ext-apps`](#command-line-parameters) for force adding extra apps to external build.
- `fap_snake_game_list`, etc - generate source + assembler listing for app's `.fap`.
@@ -103,7 +103,7 @@ To use language servers other than the default VS Code C/C++ language server, us
- `proto_ver` - generate `.h` with a protobuf version
- `dolphin_internal`, `dolphin_blocking` - generate `.c+.h` for corresponding dolphin assets
## Command-line parameters
## Command-line parameters {#command-line-parameters}
- `--options optionfile.py` (default value `fbt_options.py`) - load a file with multiple configuration values
- `--extra-int-apps=app1,app2,appN` - force listed apps to be built as internal with the `firmware` target

26
documentation/file_formats/BadUsbScriptFormat.md
View File

@@ -1,21 +1,23 @@
# Command syntax
# BadUSB File Format {#badusb_file_format}
## Command syntax
BadUsb app uses extended Duckyscript syntax. It is compatible with classic USB Rubber Ducky 1.0 scripts but provides some additional commands and features, such as custom USB ID, ALT+Numpad input method, SYSRQ command, and more functional keys.
# Script file format
## Script file format
BadUsb app can execute only text scripts from `.txt` files, no compilation is required. Both `\n` and `\r\n` line endings are supported. Empty lines are allowed. You can use spaces or tabs for line indentation.
# Command set
## Command set
## Comment line
### Comment line
Just a single comment line. The interpreter will ignore all text after the REM command.
| Command | Parameters | Notes |
| ------- | ------------ | ----- |
| REM | Comment text | |
## Delay
### Delay
Pause script execution by a defined time.
| Command | Parameters | Notes |
@@ -24,7 +26,7 @@ Pause script execution by a defined time.
| DEFAULT_DELAY | Delay value in ms | Add delay before every next command |
| DEFAULTDELAY | Delay value in ms | Same as DEFAULT_DELAY |
## Special keys
### Special keys
| Command | Notes |
| ------------------ | ---------------- |
@@ -53,7 +55,7 @@ Pause script execution by a defined time.
| APP | Same as MENU |
| Fx | F1-F12 keys |
## Modifier keys
### Modifier keys
Can be combined with a special key command or a single character.
| Command | Notes |
@@ -85,7 +87,7 @@ Will wait indefinitely for a button to be pressed
| WAIT_FOR_BUTTON_PRESS | None | Will wait for the user to press a button to continue script execution |
## String
### String
| Command | Parameters | Notes |
| ------- | ----------- | ----------------- |
@@ -100,13 +102,13 @@ Delay between keypresses.
| STRING_DELAY | Delay value in ms | Applied once to next appearing STRING command |
| STRINGDELAY | Delay value in ms | Same as STRING_DELAY |
## Repeat
### Repeat
| Command | Parameters | Notes |
| ------- | ---------------------------- | ----------------------- |
| REPEAT | Number of additional repeats | Repeat previous command |
## ALT+Numpad input
### ALT+Numpad input
On Windows and some Linux systems, you can print characters by holding `ALT` key and entering its code on Numpad.
| Command | Parameters | Notes |
@@ -115,14 +117,14 @@ On Windows and some Linux systems, you can print characters by holding `ALT` key
| ALTSTRING | Text string | Print text string using ALT+Numpad method |
| ALTCODE | Text string | Same as ALTSTRING, presents in some Duckyscript implementations |
## SysRq
### SysRq
Send [SysRq command](https://en.wikipedia.org/wiki/Magic_SysRq_key)
| Command | Parameters | Notes |
| ------- | ---------------- | ----- |
| SYSRQ | Single character | |
## USB device ID
### USB device ID
You can set the custom ID of the Flipper USB HID device. ID command should be in the **first line** of script, it is executed before script run.

27
documentation/file_formats/InfraredFileFormats.md
View File

@@ -1,7 +1,7 @@
# Infrared Flipper File Formats
# Infrared Flipper File Formats {#infrared_file_format}
## Supported protocols list for "type: parsed"
## Supported protocols list for `type: parsed`
```
NEC
NECext
@@ -17,6 +17,7 @@
Kaseikyo
RCA
```
## Infrared Remote File Format
### Example
@@ -51,7 +52,7 @@ Each button is separated from others by a comment character (`#`) for better rea
Known protocols are represented in the `parsed` form, whereas non-recognized signals may be saved and re-transmitted as `raw` data.
#### Version history:
#### Version history
1. Initial version.
@@ -72,19 +73,19 @@ Known protocols are represented in the `parsed` form, whereas non-recognized sig
### Examples
- [TV Universal Library](/applications/main/infrared/resources/infrared/assets/tv.ir)
- [A/C Universal Library](/applications/main/infrared/resources/infrared/assets/ac.ir)
- [Audio Universal Library](/applications/main/infrared/resources/infrared/assets/audio.ir)
- [TV Universal Library](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/applications/main/infrared/resources/infrared/assets/tv.ir)
- [A/C Universal Library](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/applications/main/infrared/resources/infrared/assets/ac.ir)
- [Audio Universal Library](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/applications/main/infrared/resources/infrared/assets/audio.ir)
### Description
Filename extension: `.ir`
This file format is used to store universal remote libraries. It is identical to the previous format, differing only in the `Filetype` field.\
This file format is used to store universal remote libraries. It is identical to the previous format, differing only in the `Filetype` field.
It also has predefined button names for each universal library type, so that the universal remote application can understand them.
See [Universal Remotes](/documentation/UniversalRemotes.md) for more information.
See [Universal Remotes](../UniversalRemotes.md) for more information.
### Version history:
### Version history
1. Initial version.
@@ -92,7 +93,7 @@ See [Universal Remotes](/documentation/UniversalRemotes.md) for more information
### Examples
See [Infrared Unit Tests](/applications/debug/unit_tests/resources/unit_tests/infrared/) for various examples.
See [Infrared Unit Tests](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests/resources/unit_tests/infrared) for various examples.
### Description
@@ -103,10 +104,10 @@ It is mostly similar to the two previous formats, with the main difference being
Each infrared protocol must have corresponding unit tests complete with an `.irtest` file.
Known protocols are represented in the `parsed_array` form, whereas raw data has the `raw` type.\
Known protocols are represented in the `parsed_array` form, whereas raw data has the `raw` type.
Note: a single parsed signal must be represented as an array of size 1.
### Version history:
### Version history
1. Initial version.
@@ -141,4 +142,4 @@ and the number is a sequential integer: 1, 2, 3, etc., which produces names like
| decoder_expected | parsed_array | An array of parsed signals containing the expected decoder output. Also used as the encoder input. |
| encoder_decoder_input | parsed_array | An array of parsed signals containing both the encoder-decoder input and expected output. |
See [Unit Tests](/documentation/UnitTests.md#infrared) for more info.
See [Unit Tests](../UnitTests.md) for more info.

2
documentation/file_formats/LfRfidFileFormat.md
View File

@@ -1,4 +1,4 @@
# LF RFID key file format
# LF RFID key file format {#lfrfid_file_format}
## Example

2
documentation/file_formats/NfcFileFormats.md
View File

@@ -1,4 +1,4 @@
# NFC Flipper File Formats
# NFC Flipper File Formats {#nfc_file_format}
## UID + Header (General format)

30
documentation/file_formats/SubGhzFileFormats.md
View File

@@ -1,20 +1,20 @@
# File Formats for Flipper's SubGhz Subsystem
# SubGhz Subsystem File Formats {#subghz_file_format}
## `.sub` File Format
## .sub File Format
Flipper uses `.sub` files to store SubGhz transmissions. These are text files in Flipper File Format. `.sub` files can contain either a SubGhz Key with a certain protocol or SubGhz RAW data.
Flipper uses `.sub` files to store SubGhz signals. These files use the Flipper File Format. `.sub` files can contain either a SubGhz Key with a certain protocol or SubGhz RAW data.
A `.sub` files consist of 3 parts:
A `.sub` file consist of 3 parts:
- **header**, contains file type, version, and frequency
- **header**, contains the file type, version, and frequency
- **preset information**, preset type and, in case of a custom preset, transceiver configuration data
- **protocol and its data**, contains protocol name and its specific data, such as key, bit length, etc., or RAW data
Flipper's SubGhz subsystem uses presets to configure the radio transceiver. Presets are used to configure modulation, bandwidth, filters, etc. There are several presets available in stock firmware, and there is a way to create custom presets. See [SubGhz Presets](#adding-a-custom-preset) for more details.
Flipper's SubGhz subsystem uses presets to configure the radio transceiver. Presets are used to configure modulation, bandwidth, filters, etc. There are several presets available in stock firmware, and there is a way to create custom presets. See [SubGhz Presets](#adding-a-custom-preset) section for more details.
## Header format
Header is a mandatory part of `.sub` file. It contains file type, version, and frequency.
Header is a mandatory part of a `.sub` file. It contains the file type, version, and frequency.
| Field | Type | Description |
| ----------- | ------ | ----------------------------------------------------------------- |
@@ -41,7 +41,7 @@ Built-in presets:
- `FuriHalSubGhzPreset2FSKDev238Async` — 2 Frequency Shift Keying, deviation 2kHz, 270kHz bandwidth, async(IO throw GP0)
- `FuriHalSubGhzPreset2FSKDev476Async` — 2 Frequency Shift Keying, deviation 47kHz, 270kHz bandwidth, async(IO throw GP0)
### Transceiver Configuration Data
### Transceiver Configuration Data {#transceiver-configuration-data}
Transceiver configuration data is a string of bytes, encoded in hex format, separated by spaces. For CC1101 data structure is: `XX YY XX YY .. 00 00 ZZ ZZ ZZ ZZ ZZ ZZ ZZ ZZ`, where:
@@ -54,7 +54,7 @@ You can find more details in the [CC1101 datasheet](https://www.ti.com/lit/ds/sy
## File Data
`.sub` file data section contains either key data — protocol name and its specific data, bit length, etc., or RAW data — an array of signal timings, recorded without any protocol-specific processing.
`.sub` file data section can either contain key data, consisting of a protocol name and its specific data, bit length, etc., or RAW data, which consists of an array of signal timings, recorded without any protocol-specific processing.
### Key Files
@@ -88,20 +88,20 @@ RAW `.sub` files contain raw signal data that is not processed through protocol-
For RAW files, 2 fields are required:
- **Protocol**, must be `RAW`
- **RAW_Data**, contains an array of timings, specified in microseconds Values must be non-zero, start with a positive number, and interleaved (change sign with each value). Up to 512 values per line. Can be specified multiple times to store multiple lines of data.
- **RAW_Data**, contains an array of timings, specified in microseconds. Values must be non-zero, start with a positive number, and interleaved (change sign with each value). Up to 512 values per line. Can be specified multiple times to store multiple lines of data.
Example of RAW data:
Protocol: RAW
RAW_Data: 29262 361 -68 2635 -66 24113 -66 11 ...
Long payload not fitting into internal memory buffer and consisting of short duration timings (< 10us) may not be read fast enough from the SD card. That might cause the signal transmission to stop before reaching the end of the payload. Ensure that your SD Card has good performance before transmitting long or complex RAW payloads.
A long payload that doesn't fit into the internal memory buffer and consists of short duration timings (< 10us) may not be read fast enough from the SD card. That might cause the signal transmission to stop before reaching the end of the payload. Ensure that your SD Card has good performance before transmitting long or complex RAW payloads.
### BIN_RAW Files
BinRAW `.sub` files and `RAW` files both contain data that has not been decoded by any protocol. However, unlike `RAW`, `BinRAW` files only record a useful repeating sequence of durations with a restored byte transfer rate and without broadcast noise. These files can emulate nearly all static protocols, whether Flipper knows them or not.
- Usually, you have to receive the signal a little longer so that Flipper accumulates sufficient data for correct analysis.
- Usually, you have to receive the signal a little longer so that Flipper accumulates sufficient data to analyze it correctly.
For `BinRAW` files, the following parameters are required and must be aligned to the left:
@@ -188,7 +188,7 @@ Data_RAW: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 DE 02 D3 54 D5 4C D2 C
SubGhz application provides support for adding extra radio presets and additional keys for decoding transmissions in certain protocols.
## SubGhz `keeloq_mfcodes_user` file
## SubGhz keeloq_mfcodes_user file
This file contains additional manufacturer keys for Keeloq protocol. It is used to decode Keeloq transmissions.
This file is loaded at subghz application start and is located at path `/ext/subghz/assets/keeloq_mfcodes_user`.
@@ -228,7 +228,7 @@ For each key, a name and encryption method must be specified, according to comme
AABBCCDDEEFFAABB:1:Test1
AABBCCDDEEFFAABB:1:Test2
## SubGhz `setting_user` file
## SubGhz setting_user file
This file contains additional radio presets and frequencies for SubGhz application. It is used to add new presets and frequencies for existing presets. This file is being loaded on subghz application start and is located at path `/ext/subghz/assets/setting_user`.
@@ -256,7 +256,7 @@ Header must contain the following fields:
Repeating the same frequency will cause Flipper to listen to this frequency more often.
#### Adding a Custom Preset
#### Adding a Custom Preset {#adding-a-custom-preset}
You can have as many presets as you want. Presets are embedded into `.sub` files, so another Flipper can load them directly from that file.
Each preset is defined by the following fields:

2
documentation/file_formats/iButtonFileFormat.md
View File

@@ -1,4 +1,4 @@
# iButton key file format
# iButton key file format {#ibutton_file_format}
## Example