DarkFlippers/unleashed-firmware
1
1
Fork 0
mirror of https://github.com/DarkFlippers/unleashed-firmware.git synced 2024-11-23 10:01:58 +03:00
Code Issues Projects Releases Wiki Activity

Documentation: edit texts, markdown linting (#2226)

Browse Source 
Co-authored-by: konerini <25254561+konerini@users.noreply.github.com>
Co-authored-by: あく <alleteam@gmail.com>
This commit is contained in:
knrn-ai 2023-01-06 21:18:43 +03:00 committed by GitHub
parent fa223a4f4b
commit c24bea6b06
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 509 additions and 485 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
documentation/AppManifests.md
View File

@ -1,65 +1,63 @@
# Flipper Application Manifests (.fam)
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.
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#firmware-application-set) for details on build configurations.
## Application definition
A firmware component's properties are declared in a Python code snippet, forming a call to App() function with various parameters.
A firmware component's properties are declared in a Python code snippet, forming a call to the `App()` function with various parameters.
Only 2 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
* **appid**: string, application id within the build system. Used to specify which applications to include in the build configuration and resolve dependencies and conflicts.
- **appid**: string, application ID within the build system. It is used to specify which applications to include in the build configuration and resolve dependencies and conflicts.
* **apptype**: member of FlipperAppType.* enumeration. Valid values are:
- **apptype**: member of FlipperAppType.\* enumeration. Valid values are:
| Enum member | Firmware component type |
|--------------|--------------------------|
| SERVICE | System service, created at early startup |
| SYSTEM | Application is not being shown in any menus. It can be started by other apps or from CLI |
| APP | Regular application for the main menu |
| PLUGIN | Application to be built as a part of the firmware and to be placed in the Plugins menu |
| DEBUG | Application only visible in Debug menu with debug mode enabled |
| ARCHIVE | One and only Archive app |
| SETTINGS | Application to be placed in the system settings menu |
| STARTUP | Callback function to run at system startup. Does not define a separate app |
| EXTERNAL | Application to be built as .fap plugin |
| METAPACKAGE | Does not define any code to be run, used for declaring dependencies and application bundles |
* **name**: Name that is displayed in menus.
* **entry_point**: C function to be used as the application's entry point. Note that C++ function names are mangled, so you need to wrap them in `extern "C"` to use them as entry points.
* **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.
* **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 that the current application conflicts with. 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 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.
* **order**: Order of an application within its group when sorting entries in it. The lower the order is, the closer to the start of the list the item is placed. *Used for ordering startup hooks and menu entries.*
* **sdk_headers**: List of C header files from this app's code to include in API definitions for external applications.
* **targets**: list of strings, target names, which this application is compatible with. If not specified, the application is built for all targets. The default value is `["all"]`.
| Enum member | Firmware component type |
| ----------- | ------------------------------------------------------------------------------------------- |
| SERVICE | System service, created at early startup |
| SYSTEM | Application is not being shown in any menus. It can be started by other apps or from CLI |
| APP | Regular application for the main menu |
| PLUGIN | Application to be built as a part of the firmware and to be placed in the Plugins menu |
| DEBUG | Application only visible in Debug menu with debug mode enabled |
| ARCHIVE | One and only Archive app |
| SETTINGS | Application to be placed in the system settings menu |
| STARTUP | Callback function to run at system startup. Does not define a separate app |
| EXTERNAL | Application to be built as `.fap` plugin |
| METAPACKAGE | Does not define any code to be run, used for declaring dependencies and application bundles |
- **name**: name displayed in menus.
- **entry_point**: C function to be used as the application's entry point. Note that C++ function names are mangled, so you need to wrap them in `extern "C"` to use them as entry points.
- **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.
- **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.
- **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.
- **order**: order of an application within its group when sorting entries in it. The lower the order is, the closer to the start of the list the item is placed. _Used for ordering startup hooks and menu entries._
- **sdk_headers**: list of C header files from this app's code to include in API definitions for external applications.
- **targets**: list of strings and target names with which this application is compatible. If not specified, the application is built for all targets. The default value is `["all"]`.
#### Parameters for external applications
The following parameters are used only for [FAPs](./AppsOnSDCard.md):
* **sources**: list of strings, file name masks used for gathering sources within the app folder. The default value of `["*.c*"]` includes C and C++ source files. Applications cannot use the `"lib"` folder for their own source code, as it is reserved for **fap_private_libs**.
* **fap_version**: tuple, 2 numbers in the form of (x,y): application version to be embedded within .fap file. The default value is (0,1), meaning version "0.1".
* **fap_icon**: name of a .png file, 1-bit color depth, 10x10px, to be embedded within .fap file.
* **fap_libs**: list of extra libraries to link the application against. Provides access to extra functions that are not exported as a part of main firmware at the expense of increased .fap file size and RAM consumption.
* **fap_category**: string, may be empty. App subcategory, also determines the path of the FAP within apps folder in the file system.
* **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 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.
Note that commands are executed at the firmware root folder's root, 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`**.
- **sources**: list of strings, file name masks used for gathering sources within the app folder. The default value of `["*.c*"]` includes C and C++ source files. Applications cannot use the `"lib"` folder for their own source code, as it is reserved for **fap_private_libs**.
- **fap_version**: tuple, 2 numbers in the form of (x,y): application version to be embedded within .fap file. The default value is (0,1), meaning version "0.1".
- **fap_icon**: name of a `.png` file, 1-bit color depth, 10x10px, to be embedded within `.fap` file.
- **fap_libs**: list of extra libraries to link the application against. Provides access to extra functions that are not exported as a part of main firmware at the expense of increased `.fap` file size and RAM consumption.
- **fap_category**: string, may be empty. App subcategory, also determines the path of the FAP within the apps folder in the file system.
- **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.
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:
@ -73,16 +71,16 @@ Example for building an app from Rust sources:
),
```
* **fap_private_libs**: a list of additional libraries distributed as sources alongside the application. These libraries will be built as a part of the application build process.
Library sources must be placed in a subfolder of "`lib`" folder within the application's source folder.
Each library is defined as a call to `Lib()` function, accepting the following parameters:
- **fap_private_libs**: list of additional libraries distributed as sources alongside the application. These libraries will be built as a part of the application build process.
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 library's folder. Required.
- **fap_include_paths**: list of library's relative paths to add to 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,15 +103,14 @@ 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 `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 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
.fam file contains one or more Application definitions. For example, here's a part of `applications/service/bt/application.fam`:
The `.fam` file contains one or more application definitions. For example, here's a part of `applications/service/bt/application.fam`:
```python
App(
@ -137,4 +134,4 @@ App(
)
```
For more examples, see .fam files from various firmware parts.
For more examples, see `.fam` files from various firmware parts.

67
documentation/AppsOnSDCard.md
View File

@ -1,83 +1,80 @@
# FAP (Flipper Application Package)
[fbt](./fbt.md) has support for building applications as FAP files. FAP are essentially .elf executables with extra metadata and resources bundled in.
[fbt](./fbt.md) supports building applications as FAP files. FAPs are essentially `.elf` executables with extra metadata and resources bundled in.
FAPs are built with `faps` target. They can also be deployed to `dist` folder with `fap_dist` target.
FAPs are built with the `faps` target. They can also be deployed to the `dist` folder with the `fap_dist` target.
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
FAPs are created and developed the same way as internal applications that are part of the firmware.
FAPs are created and developed the same way as internal applications that are part of the firmware.
To build your application as a FAP, just create a folder with your app's source code in `applications_user`, then write its code the way you'd do when creating a regular built-in application. Then configure its `application.fam` manifest — and set its *apptype* to FlipperAppType.EXTERNAL. See [Application Manifests](./AppManifests.md#application-definition) for more details.
* To build your application, run `./fbt fap_{APPID}`, where APPID is your application's ID in its manifest.
* To build your app, then upload it over USB & run it on Flipper, use `./fbt launch_app APPSRC=applications/path/to/app`. This command is configured in default [VSCode profile](../.vscode/ReadMe.md) as "Launch App on Flipper" build action (Ctrl+Shift+B menu).
* To build all FAPs, run `./fbt faps` or `./fbt fap_dist`.
To build your application as a FAP, create a folder with your app's source code in `applications_user`, then write its code the way you'd do when creating a regular built-in application. Then configure its `application.fam` manifest, and set its _apptype_ to FlipperAppType.EXTERNAL. See [Application Manifests](./AppManifests.md#application-definition) for more details.
- To build your application, run `./fbt fap_{APPID}`, where APPID is your application's ID in its manifest.
- To build your app and upload it over USB to run on Flipper, use `./fbt launch_app APPSRC=applications/path/to/app`. This command is configured in the default [VS Code profile](../.vscode/ReadMe.md) as a "Launch App on Flipper" build action (Ctrl+Shift+B menu).
- To build all FAPs, run `./fbt faps` or `./fbt fap_dist`.
## FAP assets
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 `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#application-definition) 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 must 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#asset-naming-rules) 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 VSCode 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 main firmware — inspect variables, set breakpoints, step through the code, etc.
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.
### Setting up debugging environment
Debugging support script looks up debugging information in the latest firmware build dir (`build/latest`). That directory is symlinked by fbt to the latest firmware configuration (Debug or Release) build dir, when you run `./fbt` for chosen configuration. See [fbt docs](./fbt.md#nb) for details.
The debugging support script looks up debugging information in the latest firmware build directory (`build/latest`). That directory is symlinked by `fbt` to the latest firmware configuration (Debug or Release) build directory when you run `./fbt` for the chosen configuration. See [fbt docs](./fbt.md#nb) for details.
To debug FAPs, do the following:
So, 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](#how-to-set-up-an-application-to-be-built-as-a-fap) and run it on Flipper
After that, you can attach with `./fbt debug` or VSCode and use all debug features.
After that, you can attach with `./fbt debug` or VS Code and use all debug features.
It is **important** that firmware and application build type (debug/release) match, and that matching firmware folder is linked as `build/latest`. Otherwise, debugging will not work.
It is **important** that firmware and application build type (debug/release) match and that the matching firmware folder is linked as `build/latest`. Otherwise, debugging will not work.
## How Flipper runs an application from an SD card
## How Flipper runs an application from SD card
Flipper's MCU cannot run code directly from external storage, so it needs to be copied to RAM first. That is done by the App Loader application responsible for loading the FAP from the SD card, verifying its integrity and compatibility, copying it to RAM, and adjusting it for its new location.
Flipper's MCU cannot run code directly from external storage, so it needs to be copied to RAM first. That is done by the App Loader application, which is responsible for loading the FAP from SD card, verifying its integrity and compatibility, copying it to RAM and adjusting it for its new location.
Since FAP has to be loaded to RAM to be executed, the amount of RAM available for allocations from heap is reduced compared to running the same app from flash, as a part of the firmware. Note that the amount of occupied RAM is less than the total FAP file size since only code and data sections are allocated, while the FAP file includes extra information only used at app load time.
Since FAP has to be loaded to RAM to be executed, the amount of RAM available for allocations from heap is reduced compared to running the same app from flash, as a part of firmware. Note that the amount of occupied RAM is less than total FAP file size, since only code and data sections are allocated, while FAP file includes extra information only used at app load time.
Applications are built for a specific API version. It is a part of the hardware target's definition and contains a major and minor version number. The App Loader checks if the application's major API version matches the firmware's major API version.
Applications are built for a specific API version. It is a part of the hardware target's definition and contains a major and minor version number. Application loader checks if the application's major API version matches firmware's major API version.
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.
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
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 `firmware/targets/` directory.
## API Versioning
Not all parts of firmware are available for external applications. A subset of available functions and variables is defined in "api_symbols.csv" file, which is a part of firmware target definition in `firmware/targets/` directory.
**`fbt`** uses semantic versioning for API. Major version is incremented when there are breaking changes in the API, 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:
- removal of 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 .csv file. New entries are marked with "`?`" mark, and the user is supposed to change the mark to "`+`" for the entry to be exposed for FAPs, "`-`" for it to be unavailable.
- 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.
**`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
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. Such application won't be able to run on the device until all requires 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.

103
documentation/KeyCombo.md
View File

@ -1,134 +1,119 @@
# Key Combos
There are times when your Flipper feels blue and doesn't respond to your commands.
In that case, you may find this guide useful.
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.
## Basic combos
## Basic Combos
### Hardware Reset
### Hardware reset
- Press `LEFT` and `BACK` and hold for a couple of seconds
- Release `LEFT` and `BACK`
This combo performs a hardware reset by pulling MCU reset line down.
Main components involved: Keys -> DD8(NC7SZ32M5X, OR-gate) -> DD1(STM32WB55, MCU)
This combo performs a hardware reset by pulling the MCU reset line down.
Main components involved: Keys -> DD8(NC7SZ32M5X, OR-gate) -> DD1(STM32WB55, MCU).
There is 1 case where it does not work:
- MCU debug block is active and holding reset line from inside.
It won't work only in one case:
- The MCU debug block is active and holding the reset line from inside.
### Hardware Power Reset
- Disconnect USB and any external power supplies
- Disconnect USB once again
- Make sure that you've disconnected USB and any external power supplies
- Press `BACK` and hold for 30 seconds (Will only work with USB disconnected)
- If you have not disconnected USB, then disconnect USB and repeat previous step
- Release `BACK` key
- Disconnect the USB cable and any external power supplies
- Disconnect the USB once again
- Make sure you've disconnected the USB and any external power supplies
- Press `BACK` and hold for 30 seconds (this will only work with the USB disconnected)
- If you haven't disconnected the USB, then disconnect it and repeat the previous step
- Release the `BACK` key
This combo performs a reset by switching SYS power line off and then on.
Main components involved: Keys -> DD6(bq25896, charger)
Main components involved: Keys -> DD6(bq25896, charger).
There is 1 case where it does not work:
It won't work only in one case:
- Power supply is connected to USB or 5V_ext
### Software DFU
- Press `LEFT` on boot to enter DFU with Flipper boot-loader
There is 1 case where it does not work:
It won't work only in one case:
- Flipper boot-loader is damaged or absent
### Hardware DFU
- Press `OK` on boot to enter DFU with ST boot-loader
There is 1 case where it does not work:
It won't work only in one case:
- Option Bytes are damaged or set to ignore `OK` key
## DFU Combos
- Option Bytes are damaged or set to ignore the `OK` key
## DFU combos
### Hardware Reset + Software DFU
- Press `LEFT` and `BACK` and hold for a couple of seconds
- Release `BACK`
- Device will enter DFU with indication (Blue LED + DFU Screen)
- Device will enter DFU with an indication (Blue LED + DFU Screen)
- Release `LEFT`
This combo performs a hardware reset by pulling MCU reset line down.
Then, `LEFT` key indicates to the boot-loader that DFU mode is requested.
This combo performs a hardware reset by pulling the MCU reset line down. Then, the `LEFT` key indicates to the boot-loader that DFU mode is requested.
There are 2 cases where it does not work:
It won't work in two cases:
- MCU debug block is active and holding reset line from inside
- The MCU debug block is active and holding the reset line from inside
- Flipper boot-loader is damaged or absent
### Hardware Reset + Hardware DFU
- Press `LEFT`, `BACK` and `OK` and hold for a couple of seconds
- Release `BACK` and `LEFT`
- Device will enter DFU without indication
- The device will enter DFU without an indication
This combo performs a hardware reset by pulling MCU reset line down.
Then, `OK` key forces MCU to load internal boot-loader.
This combo performs a hardware reset by pulling the MCU reset line down. Then, the `OK` key forces MCU to load the internal boot-loader.
There are 2 cases where it does not work:
- MCU debug block is active and holding reset line from inside
- Option Bytes are damaged or set to ignore `OK` key
It won't work in two cases:
- The MCU debug block is active and holding the reset line from inside
- Option Bytes are damaged or set to ignore the `OK` key
### Hardware Power Reset + Software DFU
- Disconnect USB and any external power supplies
- Disconnect the USB and any external power supplies
- Press `BACK` and `LEFT` for 30 seconds
- Release `BACK`
- Device will enter DFU with indication (Blue LED + DFU Screen)
- The device will enter DFU with an indication (Blue LED + DFU Screen)
- Release `LEFT`
- Plug in USB
- Plug in the USB
This combo performs a reset by switching SYS power line off and then on.
Then, `LEFT` key indicates to boot-loader that DFU mode requested.
This combo performs a reset by switching the SYS power line off and then on. Next, the `LEFT` key indicates to the boot-loader that DFU mode is requested.
There are 2 cases where it does not work:
It won't work in two cases:
- Power supply is connected to USB or 5V_ext
- Flipper boot-loader is damaged or absent
### Hardware Power Reset + Hardware DFU
- Disconnect USB and any external power supplies
- Disconnect the USB and any external power supplies
- Press `BACK` and `OK` and hold for 30 seconds
- Release `BACK` and `OK`
- Device will enter DFU without indication
- Plug USB
- The device will enter DFU without indication
- Plug in the USB
This combo performs a reset by switching SYS power line off and then on.
Then, `OK` key forces MCU to load internal boot-loader.
This combo performs a reset by switching the SYS power line off and then on. Next, the `OK` key forces MCU to load the internal boot-loader.
There are 2 cases where it does not work:
It won't work in two cases:
- Power supply is connected to USB or 5V_ext
- Option Bytes are damaged or set to ignore `OK` key
- Option Bytes are damaged or set to ignore the `OK` key
# Alternative ways to recover your device
If none of the described methods were useful:
If none of the described methods helped you:
- Ensure the battery charged
- Disconnect the battery and connect again (Requires disassembly)
- Try to Flash device with ST-Link or other programmer that supports SWD
- Make sure the battery charged
- Disconnect the battery and connect again (requires disassembly)
- Try to flash the device with ST-Link or another programmer that supports SWD
If you still are here and your device is not working: it's not a software issue.
If you're still here and your device is not working: it's not a software issue.

108
documentation/OTA.md
View File

@ -1,84 +1,79 @@
# 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 whole Flipper's flash memory — something that's not possible when running main code from the same flash.
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?
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 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 upon the firmware, we back up current configuration from `/int/` into a plain tar archive on SD card.
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
For that, main firmware loads an updater image - a customized build of main Flipper firmware — into RAM and runs it. Updater performs operations on system flash that are described by an Update manifest file.
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.
First, if there's a Radio stack image bundled with the update, updater compares its version with currently installed one. If they don't match, updater performs stack deinstallation followed by writing and installing a new one. The installation itself is performed by proprietary software, FUS, running on Core2, and leads to a series of system restarts.
First, if there's a Radio stack image bundled with the update, updater compares its version with the currently installed one. If they don't match, updater performs stack deinstallation followed by writing and installing a new one. The installation itself is performed by proprietary software FUS running on Core2, and leads to a series of system restarts.
Then, updater validates and corrects Option Bytes — a special memory region containing low-level configuration for Flipper's MCU.
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
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 SD card.
If the update package contains an additional resources archive, it is extracted onto the SD card.
# Update manifest
Update packages come 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.
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
An update manifest must contain the following keys in given order:
An update manifest must contain the following keys in the given order:
* __Filetype__: a constant string, "Flipper firmware upgrade configuration";
- **Filetype**: a constant string, "Flipper firmware upgrade configuration".
* __Version__: manifest version. Current value is 2;
- **Version**: manifest version. The current value is 2.
* __Info__: arbitrary string, describing package contents;
- **Info**: arbitrary string, describing package contents.
* __Target__: hardware revision the package is built for;
- **Target**: hardware revision for which the package is built.
* __Loader__: file name of stage 2 loader that is executed from RAM;
- **Loader**: file name of stage 2 loader that is executed from RAM.
* __Loader CRC__: CRC32 of loader file. Note that it is represented in little-endian hex.
- **Loader CRC**: CRC32 of loader file. Note that it is represented in little-endian hex.
## Optional fields
Other fields may have empty values, is such case, updater skips all operations related to such values.
Other fields may have empty values. In this case, updater skips all operations related to these values.
* __Radio__: file name of radio stack image, provided by STM;
- **Radio**: file name of radio stack image, provided by STM.
* __Radio address__: address to install the radio stack at. It is specified in Release Notes by STM;
- **Radio address**: address to install the radio stack at. It is specified in Release Notes by STM.
* __Radio version__: Radio major, minor and sub versions followed by branch, release, and stack type packed into 6 hex-encoded bytes;
- **Radio version**: radio major, minor and sub versions followed by branch, release and stack type packed into 6 hex-encoded bytes.
* __Radio CRC__: CRC32 of radio image;
- **Radio CRC**: CRC32 of radio image.
* __Resources__: file name of TAR archive with resources to be extracted on SD card;
* __OB reference__, __OB mask__, __OB write mask__: reference values for validating and correcting option bytes.
- **Resources**: file name of TAR archive with resources to be extracted onto the SD card.
- **OB reference**, **OB mask**, **OB write mask**: reference values for validating and correcting option bytes.
# OTA update error codes
We designed the OTA update process to be as fail-safe as possible. We don't start any risky operation before validating all related pieces of data to ensure we don't leave the device in a partially updated, or bricked, state.
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.
Even if something goes wrong, Updater gives you an option to retry failed operations, and reports its state with an error code. These error codes have an `[XX-YY]` format, where `XX` encodes an operation that failed, and `YY` contains extra details on its progress where the error occurred.
Even if something goes wrong, updater allows you to retry failed operations and reports its state with an error code. These error codes have an `[XX-YY]` format, where `XX` encodes the failed operation, and `YY` contains extra details on its progress where the error occurred.
| Stage description | Code | Progress | Description |
|:-----------------------:|-------:|------------|--------------------------------------------|
| :---------------------: | -----: | ---------- | ------------------------------------------ |
| Loading update manifest | **1** | **13** | Updater reported hardware version mismatch |
| | | **20** | Failed to get saved manifest path |
| | | **30** | Failed to load manifest |
@ -86,61 +81,60 @@ Even if something goes wrong, Updater gives you an option to retry failed operat
| | | **50** | Package has mismatching HW target |
| | | **60** | Missing DFU file |
| | | **80** | Missing radio firmware file |
| Backing up LFS | **2** | **0-100** | FS read/write error |
| Checking radio FW | **3** | **0-99** | Error reading radio firmware file |
| Backing up LFS | **2** | **0-100** | FS read/write error |
| Checking radio FW | **3** | **0-99** | Error reading radio firmware file |
| | | **100** | CRC mismatch |
| Uninstalling radio FW | **4** | **0** | SHCI Delete command error |
| Uninstalling radio FW | **4** | **0** | SHCI Delete command error |
| | | **80** | Error awaiting command status |
| Writing radio FW | **5** | **0-100** | Block read/write error |
| Installing radio FW | **6** | **0** | SHCI Install command error |
| Writing radio FW | **5** | **0-100** | Block read/write error |
| Installing radio FW | **6** | **0** | SHCI Install command error |
| | | **80** | Error awaiting command status |
| Radio is updating | **7** | **10** | Error waiting for operation completion |
| Validating opt. bytes | **8** | **yy** | Option byte code |
| Checking DFU file | **9** | **0** | Error opening DFU file |
| Radio is updating | **7** | **10** | Error waiting for operation completion |
| Validating opt. bytes | **8** | **yy** | Option byte code |
| Checking DFU file | **9** | **0** | Error opening DFU file |
| | | **1-98** | Error reading DFU file |
| | | **99-100** | Corrupted DFU file |
| Writing flash | **10** | **0-100** | Block read/write error |
| Validating flash | **11** | **0-100** | Block read/write error |
| Restoring LFS | **12** | **0-100** | FS read/write error |
| Updating resources | **13** | **0-100** | SD card read/write error |
| Writing flash | **10** | **0-100** | Block read/write error |
| Validating flash | **11** | **0-100** | Block read/write error |
| Restoring LFS | **12** | **0-100** | FS read/write error |
| Updating resources | **13** | **0-100** | SD card read/write error |
# Building update packages
## Full package
To build full update package, including firmware, radio stack and resources for SD card, run `./fbt COMPACT=1 DEBUG=0 updater_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
To build minimal update package, including only firmware, run `./fbt COMPACT=1 DEBUG=0 updater_minpackage`
To build a minimal update package, including only firmware, run:
`./fbt COMPACT=1 DEBUG=0 updater_minpackage`
## 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 passing stack type and binary name to `fbt`:
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`:
`./fbt updater_package COMPACT=1 DEBUG=0 COPRO_OB_DATA=scripts/ob_custradio.data COPRO_STACK_BIN=stm32wb5x_BLE_Stack_full_fw.bin COPRO_STACK_TYPE=ble_full`
`./fbt updater_package COMPACT=1 DEBUG=0 COPRO_OB_DATA=scripts/ob_custradio.data COPRO_STACK_BIN=stm32wb5x_BLE_Stack_full_fw.bin COPRO_STACK_TYPE=ble_full`
Note that `COPRO_OB_DATA` must point to a valid file in `scripts` folder containing reference Option Byte data matching to your radio stack type.
Note that `COPRO_OB_DATA` must point to a valid file in the `scripts` folder containing reference Option Byte data matching your radio stack type.
In certain cases, you might have to confirm your intentions by adding `COPRO_DISCLAIMER=...` to the build command line.
## Building partial update packages
You can customize package contents by calling `scripts/update.py` directly.
You can customize package contents by calling `scripts/update.py` directly.
For example, to build a package only for installing BLE FULL stack:
```shell
scripts/update.py generate \
-t f7 -d r13.3_full -v "BLE FULL 13.3" \
--stage dist/f7/flipper-z-f7-updater-*.bin \
--radio lib/STM32CubeWB/Projects/STM32WB_Copro_Wireless_Binaries/STM32WB5x/stm32wb5x_BLE_Stack_full_fw.bin \
--radiotype ble_full
-t f7 -d r13.3_full -v "BLE FULL 13.3" \
--stage dist/f7/flipper-z-f7-updater-*.bin \
--radio lib/STM32CubeWB/Projects/STM32WB_Copro_Wireless_Binaries/STM32WB5x/stm32wb5x_BLE_Stack_full_fw.bin \
--radiotype ble_full
```
For full list of options, check `scripts/update.py generate` help.
For the full list of options, check `scripts/update.py generate` help.

19
documentation/RoadMap.md
View File

@ -1,9 +1,8 @@
# RoadMap
# Where we are (0.x.x branch)
# Where we are now (0.x.x branch)
Our goal for 0.x.x branch is to build stable, usable apps and API.
The first public release in this branch is 0.43.1.
Our goal for the 0.x.x branch is to build an API and apps that are stable and usable. The first public release in this branch is 0.43.1.
## What's already implemented
@ -17,12 +16,12 @@ The first public release in this branch is 0.43.1.
- SubGhz: all most common protocols, reading RAW for everything else
- 125kHz RFID: all most common protocols
- NFC: reading/emulating Mifare Ultralight, reading MiFare Classic and DESFire, basic EMV, basic NFC-B/F/V
- NFC: reading/emulating MIFARE Ultralight, reading MIFARE Classic and DESFire, basic EMV, and basic NFC-B/F/V
- Infrared: all most common RC protocols, RAW format for everything else
- GPIO: UART bridge, basic GPIO controls
- iButton: DS1990, Cyfral, Metacom
- Bad USB: Full USB Rubber Ducky support, some extras for windows alt codes
- U2F: Full U2F specification support
- iButton: DS1990, Cyfral, Metakom
- Bad USB: full USB Rubber Ducky support, some extras for Windows Alt codes
- U2F: full U2F specification support
**External applications**
@ -42,8 +41,6 @@ The main goal for 1.0.0 is to provide the first stable version for both Users an
## When will it happen, and where can I see the progress?
Release 1.0.0 will most likely happen around the end of 2023Q1
Release 1.0.0 will likely happen around the end of 2023Q1.
Development progress can be tracked in our public Miro board:
https://miro.com/app/board/uXjVO_3D6xU=/?moveToWidget=3458764522498020058&cot=14
You can track the development progress in our public Miro board: https://miro.com/app/board/uXjVO_3D6xU=/?moveToWidget=3458764522498020058&cot=14

40
documentation/UnitTests.md
View File

@ -1,49 +1,65 @@
# 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 were correct.
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).
It is run directly on the Flipper Zero in order to employ its hardware features and to rule out any platform-related differences.
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.
When contributing code to the Flipper Zero firmware, it is highly desirable to supply unit tests along with the proposed features.
Running existing unit tests is useful to ensure that the new code doesn't introduce any regressions.
## Running unit tests
In order to run the unit tests, follow these steps:
To run the unit tests, follow these steps:
1. Compile the firmware with the tests enabled: `./fbt FIRMWARE_APP_SET=unit_tests`.
2. Flash the firmware using your preferred method.
3. Copy the [assets/unit_tests](assets/unit_tests) folder to the root of your Flipper Zero's SD card.
4. 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.
**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.
## Adding unit tests
### General
#### 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.
#### Test assets
Some unit tests require external data in order to function. These files (commonly called assets) reside in the [assets/unit_tests](/assets/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 [assets/unit_tests](/assets/unit_tests) directory in their respective subdirectories. Asset files can be of any type (plain text, FlipperFormat (FFF), binary, etc.).
### Application-specific
#### Infrared
Each infrared protocol has a corresponding set of unit tests, so it makes sense to implement one when adding support for a new protocol.
In order to add unit tests for your protocol, follow these steps:
To add unit tests for your protocol, follow these steps:
1. Create a file named `test_<your_protocol_name>.irtest` in the [assets](assets/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).
4. Update the [assets](assets/unit_tests/infrared) on your Flipper Zero and run the tests to see if they pass.
##### Test data format
Each unit test has 3 sections:
1. `decoder` - takes in raw signal and outputs decoded messages.
Each unit test has three sections:
1. `decoder` - takes in a raw signal and outputs decoded messages.
2. `encoder` - takes in decoded messages and outputs a raw signal.
3. `encoder_decoder` - takes in decoded messages, turns them into a raw signal, and then decodes again.
3. `encoder_decoder` - takes in decoded messages, turns them into a raw signal, and then decodes again.
Infrared test asset files have an `.irtest` extension and are regular `.ir` files with a few additions.
Decoder input data has signal names `decoder_input_N`, where N is a test sequence number. Expected data goes under the name `decoder_expected_N`. When testing the encoder these two are switched.
Decoder input data has signal names `decoder_input_N`, where N is a test sequence number. Expected data goes under the name `decoder_expected_N`. When testing the encoder, these two are switched.
Decoded data is represented in arrays (since a single raw signal may decode to several messages). If there is only one signal, then it has to be an array of size 1. Use the existing files as syntax examples.
Decoded data is represented in arrays (since a single raw signal may be decoded into several messages). If there is only one signal, then it has to be an array of size 1. Use the existing files as syntax examples.
##### Getting raw signals
Recording raw IR signals are possible using the Flipper Zero. Launch the CLI session, run `ir rx raw`, then point the remote towards Flipper's receiver and send the signals. The raw signal data will be printed to the console in a convenient format.

49
documentation/UniversalRemotes.md
View File

@ -1,62 +1,69 @@
# 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`, `Ch_prev`. Any of them can be omitted if not supported by the TV.
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. Don't forget to make sure that every recorded signal does what it's supposed to.
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](/assets/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`, `Mute`. Any of them can be omitted if not supported by the player.
## Audio players
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`.
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 players universal remote file](/assets/resources/infrared/assets/audio.ir).
If everything checks out, append these signals **to the end** of the [audio player universal remote file](/assets/resources/infrared/assets/audio.ir).
## Air conditioners
## 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 which shows current mode, temperature and other settings.
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`, `Heat_lo`.
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), while leaving other parameters such as fan speed or vane on **AUTO** (if applicable).
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 the steps 2-6 for each signal from the table below.
7. Repeat steps 2-6 for each signal from the table below.
| Signal | Mode | Temperature | Note |
| 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 | |
| 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 A/C is ON.
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. Any of them can be omitted, but that will mean that this functionality will not be used.
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](/assets/resources/infrared/assets/ac.ir).
## Final steps
The order of signals is not important, but they must be preceded by a following comment: `# Model: <Your model name>` in order to keep the library organised.
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.

115
documentation/fbt.md
View File

@ -5,102 +5,99 @@ It is invoked by `./fbt` in the firmware project root directory. Internally, it
## Requirements
Please install Python packages required by assets build scripts: `pip3 install -r scripts/requirements.txt`
Install Python packages required by assets build scripts: `pip3 install -r scripts/requirements.txt`
## NB
* `fbt` constructs all referenced environments & their targets' dependency trees on startup. So, to keep startup time as low as possible, we're hiding construction of certain targets behind command-line options.
* `fbt` always performs `git submodule update --init` on start, unless you set `FBT_NO_SYNC=1` in environment:
* On Windows, that's `set "FBT_NO_SYNC=1"` in the shell you're running `fbt` from
* On \*nix, it's `$ FBT_NO_SYNC=1 ./fbt ...`
* `fbt` builds updater & firmware in separate subdirectories in `build`, with their names depending on optimization settings (`COMPACT` & `DEBUG` options). However, for ease of integration with IDEs, latest built variant's directory is always linked as `built/latest`. Additionally, `compile_commands.json` is generated in that folder, which is used for code completion support in IDE.
- `fbt` constructs all referenced environments and their targets' dependency trees on startup. So, to keep startup time as low as possible, we're hiding the construction of certain targets behind command-line options.
- `fbt` always performs `git submodule update --init` on start, unless you set `FBT_NO_SYNC=1` in the environment:
- On Windows, it's `set "FBT_NO_SYNC=1"` in the shell you're running `fbt` from
- On \*nix, it's `$ FBT_NO_SYNC=1 ./fbt ...`
- `fbt` builds updater & firmware in separate subdirectories in `build`, and their names depend on optimization settings (`COMPACT` & `DEBUG` options). However, for ease of integration with IDEs, the latest built variant's directory is always linked as `built/latest`. Additionally, `compile_commands.json` is generated in that folder (used for code completion support in IDE).
## Invoking FBT
To build with FBT, call it specifying configuration options & targets to build. For example,
To build with FBT, call it and specify configuration options & targets to build. For example:
`./fbt COMPACT=1 DEBUG=0 VERBOSE=1 updater_package copro_dist`
To run cleanup (think of `make clean`) for specified targets, add `-c` option.
To run cleanup (think of `make clean`) for specified targets, add the `-c` option.
## VSCode integration
`fbt` includes basic development environment configuration for VSCode. To deploy it, run `./fbt vscode_dist`. That will copy initial environment configuration to `.vscode` folder. After that, you can use that configuration by starting VSCode and choosing firmware root folder in "File > Open Folder" menu.
* On first start, you'll be prompted to install recommended plug-ins. Please install them for best development experience. _You can find a list of them in `.vscode/extensions.json`._
* Basic build tasks are invoked in Ctrl+Shift+B menu.
* Debugging requires a supported probe. That includes:
* Wi-Fi devboard with stock firmware (blackmagic),
* ST-Link and compatible devices,
* J-Link for flashing and debugging (in VSCode only). _Note that J-Link tools are not included with our toolchain and you have to [download](https://www.segger.com/downloads/jlink/) them yourself and put on your system's PATH._
* Without a supported probe, you can install firmware on Flipper using USB installation method.
`fbt` includes basic development environment configuration for VS Code. Run `./fbt vscode_dist` to deploy it. That will copy the initial environment configuration to the `.vscode` folder. After that, you can use that configuration by starting VS Code and choosing the firmware root folder in the "File > Open Folder" menu.
- On the first start, you'll be prompted to install recommended plugins. We highly recommend installing them for the best development experience. _You can find a list of them in `.vscode/extensions.json`._
- Basic build tasks are invoked in the Ctrl+Shift+B menu.
- Debugging requires a supported probe. That includes:
- Wi-Fi devboard with stock firmware (blackmagic).
- ST-Link and compatible devices.
- J-Link for flashing and debugging (in VSCode only). _Note that J-Link tools are not included with our toolchain and you have to [download](https://www.segger.com/downloads/jlink/) them yourself and put them on your system's PATH._
- Without a supported probe, you can install firmware on Flipper using the USB installation method.
## 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.
### High-level (what you most likely need)
- `fw_dist` - build & publish firmware to `dist` folder. This is a default target, when no other are specified
- `fap_dist` - build external plugins & publish to `dist` folder
- `updater_package`, `updater_minpackage` - build self-update package. Minimal version only includes firmware's DFU file; full version also includes radio stack & resources for SD card
- `copro_dist` - bundle Core2 FUS+stack binaries for qFlipper
- `flash` - flash attached device with OpenOCD over ST-Link
- `flash_usb`, `flash_usb_full` - build, upload and install update package to device over USB. See details on `updater_package`, `updater_minpackage`
- `debug` - build and flash firmware, then attach with gdb with firmware's .elf loaded
- `debug_other`, `debug_other_blackmagic` - attach gdb without loading any .elf. Allows to manually add external elf files with `add-symbol-file` in gdb
- `updater_debug` - attach gdb with updater's .elf loaded
- `blackmagic` - debug firmware with Blackmagic probe (WiFi dev board)
- `openocd` - just start OpenOCD
- `get_blackmagic` - output blackmagic address in gdb remote format. Useful for IDE integration
- `fw_dist` - build & publish firmware to the `dist` folder. This is a default target when no others are specified.
- `fap_dist` - build external plugins & publish to the `dist` folder.
- `updater_package`, `updater_minpackage` - build a self-update package. The minimal version only includes the firmware's DFU file; the full version also includes a radio stack & resources for the SD card.
- `copro_dist` - bundle Core2 FUS+stack binaries for qFlipper.
- `flash` - flash the attached device with OpenOCD over ST-Link.
- `flash_usb`, `flash_usb_full` - build, upload and install the update package to the device over USB. See details on `updater_package` and `updater_minpackage`.
- `debug` - build and flash firmware, then attach with gdb with firmware's .elf loaded.
- `debug_other`, `debug_other_blackmagic` - attach GDB without loading any `.elf`. It will allow you to manually add external `.elf` files with `add-symbol-file` in GDB.
- `updater_debug` - attach GDB with the updater's `.elf` loaded.
- `blackmagic` - debug firmware with Blackmagic probe (WiFi dev board).
- `openocd` - just start OpenOCD.
- `get_blackmagic` - output the blackmagic address in the GDB remote format. Useful for IDE integration.
- `get_stlink` - output serial numbers for attached STLink probes. Used for specifying an adapter with `OPENOCD_ADAPTER_SERIAL=...`.
- `lint`, `format` - run clang-format on C source code to check and reformat it according to `.clang-format` specs
- `lint_py`, `format_py` - run [black](https://black.readthedocs.io/en/stable/index.html) on Python source code, build system files & application manifests
- `cli` - start Flipper CLI session over USB
- `lint`, `format` - run clang-format on the C source code to check and reformat it according to the `.clang-format` specs.
- `lint_py`, `format_py` - run [black](https://black.readthedocs.io/en/stable/index.html) on the Python source code, build system files & application manifests.
- `cli` - start a Flipper CLI session over USB.
### Firmware targets
- `faps` - build all external & plugin apps as [.faps](./AppsOnSDCard.md#fap-flipper-application-package).
- `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:
- `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
- `flash`, `firmware_flash` - flash current version to attached device with OpenOCD over ST-Link
- `jflash` - flash current version to attached device with JFlash using J-Link probe. JFlash executable must be on your $PATH
- `flash_blackmagic` - flash current version to attached device with Blackmagic probe
- `firmware_all`, `updater_all` - build basic set of binaries
- `firmware_list`, `updater_list` - generate source + assembler listing
- `firmware_cdb`, `updater_cdb` - generate `compilation_database.json` file for external tools and IDEs. It can be created without actually building the firmware.
- `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`.
- `flash`, `firmware_flash` - flash the current version to the attached device with OpenOCD over ST-Link.
- `jflash` - flash the current version to the attached device with JFlash using a J-Link probe. The JFlash executable must be on your `$PATH`.
- `flash_blackmagic` - flash the current version to the attached device with a Blackmagic probe.
- `firmware_all`, `updater_all` - build a basic set of binaries.
- `firmware_list`, `updater_list` - generate source + assembler listing.
- `firmware_cdb`, `updater_cdb` - generate a `compilation_database.json` file for external tools and IDEs. It can be created without actually building the firmware.
### Assets
- `resources` - build resources and their Manifest
- `dolphin_ext` - process dolphin animations for SD card
- `icons` - generate .c+.h for icons from png assets
- `proto` - generate .pb.c+.pb.h for .proto sources
- `proto_ver` - generate .h with protobuf version
- `dolphin_internal`, `dolphin_blocking` - generate .c+.h for corresponding dolphin assets
- `resources` - build resources and their manifest files
- `dolphin_ext` - process dolphin animations for the SD card
- `icons` - generate `.c+.h` for icons from PNG assets
- `proto` - generate `.pb.c+.pb.h` for `.proto` sources
- `proto_ver` - generate `.h` with a protobuf version
- `dolphin_internal`, `dolphin_blocking` - generate `.c+.h` for corresponding dolphin assets
## Command-line parameters
- `--options optionfile.py` (default value `fbt_options.py`) - load file with multiple configuration values
- `--extra-int-apps=app1,app2,appN` - forces listed apps to be built as internal with `firmware` target
- `--extra-ext-apps=app1,app2,appN` - forces listed apps to be built as external with `firmware_extapps` target
- `--proxy-env=VAR1,VAR2` - additional environment variables to expose to subprocesses spawned by `fbt`. By default, `fbt` sanitizes execution environment and doesn't forward all inherited environment variables. You can find list of variables that are always forwarded in `environ.scons` file.
- `--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
- `--extra-ext-apps=app1,app2,appN` - force listed apps to be built as external with the `firmware_extapps` target
- `--proxy-env=VAR1,VAR2` - additional environment variables to expose to subprocesses spawned by `fbt`. By default, `fbt` sanitizes the execution environment and doesn't forward all inherited environment variables. You can find the list of variables that are always forwarded in the `environ.scons` file.
## Configuration
## Configuration
Default configuration variables are set in the configuration file `fbt_options.py`.
Values set on command-line have higher precedence over configuration file.
Default configuration variables are set in the configuration file: `fbt_options.py`.
Values set in the command line have higher precedence over the configuration file.
You can find out available options with `./fbt -h`.
### Firmware application set
You can create customized firmware builds by modifying the application list to be included in the build. Application presets are configured with the `FIRMWARE_APPS` option, which is a map(configuration_name:str -> application_list:tuple(str)). To specify application set to use in a build, set `FIRMWARE_APP_SET` to its name.
You can create customized firmware builds by modifying the list of applications to be included in the build. Application presets are configured with the `FIRMWARE_APPS` option, which is a `map(configuration_name:str -> application_list:tuple(str))`. To specify an application set to use in the build, set `FIRMWARE_APP_SET` to its name.
For example, to build a firmware image with unit tests, run `./fbt FIRMWARE_APP_SET=unit_tests`.
Check out `fbt_options.py` for details.

108
documentation/file_formats/BadUsbScriptFormat.md
View File

@ -1,16 +1,23 @@
# 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.
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
BadUsb app can execute only text scrips from .txt files, no compilation is required. Both `\n` and `\r\n` line endings are supported. Empty lines are allowed. You can use spaces ore tabs for line indentation.
BadUsb app can execute only text scrips 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
## Comment line
Just a single comment line. All text after REM command will be ignored by interpreter
Just a single comment line. The interpreter will ignore all text after the REM command.
|Command|Parameters|Notes|
|-|-|-|
|REM|Comment text||
## Delay
Pause script execution by defined time
Pause script execution by a defined time.
|Command|Parameters|Notes|
|-|-|-|
|DELAY|Delay value in ms|Single delay|
@ -18,35 +25,37 @@ Pause script execution by defined time
|DEFAULTDELAY|Delay value in ms|Same as DEFAULT_DELAY|
## Special keys
|Command|Notes|
|-|-|
|DOWNARROW / DOWN||
|LEFTARROW / LEFT||
|RIGHTARROW / RIGHT||
|UPARROW / UP||
|ENTER||
|DELETE||
|BACKSPACE||
|END||
|HOME||
|ESCAPE / ESC||
|INSERT||
|PAGEUP||
|PAGEDOWN||
|CAPSLOCK||
|NUMLOCK||
|SCROLLLOCK||
|PRINTSCREEN||
|BREAK|Pause/Break key|
|PAUSE|Pause/Break key|
|SPACE||
|TAB||
|MENU|Context menu key|
|APP|Same as MENU|
|Fx|F1-F12 keys|
| Command | Notes |
| ------------------ | ---------------- |
| DOWNARROW / DOWN | |
| LEFTARROW / LEFT | |
| RIGHTARROW / RIGHT | |
| UPARROW / UP | |
| ENTER | |
| DELETE | |
| BACKSPACE | |
| END | |
| HOME | |
| ESCAPE / ESC | |
| INSERT | |
| PAGEUP | |
| PAGEDOWN | |
| CAPSLOCK | |
| NUMLOCK | |
| SCROLLLOCK | |
| PRINTSCREEN | |
| BREAK | Pause/Break key |
| PAUSE | Pause/Break key |
| SPACE | |
| TAB | |
| MENU | Context menu key |
| APP | Same as MENU |
| Fx | F1-F12 keys |
## Modifier keys
Can be combined with special key command or single character
Can be combined with a special key command or a single character.
|Command|Notes|
|-|-|
|CONTROL / CTRL||
@ -58,35 +67,44 @@ Can be combined with special key command or single character
|ALT-SHIFT|ALT+SHIFT|
|ALT-GUI|ALT+WIN|
|GUI-SHIFT|WIN+SHIFT|
## String
|Command|Parameters|Notes|
|-|-|-|
|STRING|Text string|Print text string|
| Command | Parameters | Notes |
| ------- | ----------- | ----------------- |
| STRING | Text string | Print text string |
## Repeat
|Command|Parameters|Notes|
|-|-|-|
|REPEAT|Number of additional repeats|Repeat previous command|
| Command | Parameters | Notes |
| ------- | ---------------------------- | ----------------------- |
| REPEAT | Number of additional repeats | Repeat previous command |
## ALT+Numpad input
On Windows and some Linux systems you can print character by pressing ALT key and entering its code on numpad
On Windows and some Linux systems, you can print characters by pressing `ALT` key and entering its code on Numpad.
|Command|Parameters|Notes|
|-|-|-|
|ALTCHAR|Character code|Print single character|
|ALTSTRING|Text string|Print text string using ALT+Numpad method|
|ALTCODE|Text string|Same as ALTSTRING, presents in some Duckyscript implementations|
## SysRq
Send [SysRq command](https://en.wikipedia.org/wiki/Magic_SysRq_key)
|Command|Parameters|Notes|
|-|-|-|
|SYSRQ|Single character||
## USB device ID
You can set custom ID of Flipper USB HID device. ID command should be in the **first line** of script, it is executed before script run.
|Command|Parameters|Notes|
|-|-|-|
|ID|VID:PID Manufacturer:Product||
## 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.
| Command | Parameters | Notes |
| ------- | ---------------------------- | ----- |
| ID | VID:PID Manufacturer:Product | |
Example:
`ID 1234:abcd Flipper Devices:Flipper Zero`
VID and PID are hex codes and are mandatory, Manufacturer and Product are text strings and are optional.
VID and PID are hex codes and are mandatory. Manufacturer and Product are text strings and are optional.

74
documentation/file_formats/InfraredFileFormats.md
View File

@ -1,11 +1,12 @@
# Infrared Flipper File Formats
## Infrared Remote File Format
### Example
Filetype: IR signals file
Version: 1
#
#
name: Button_1
type: parsed
protocol: NECext
@ -25,48 +26,59 @@
command: 15 00 00 00
### Description
Filename extension: `.ir`
This file format is used to store an infrared remote that consists of an arbitrary number of buttons.
This file format is used to store an infrared remote that consists of an arbitrary number of buttons.
Each button is separated from others by a comment character (`#`) for better readability.
Known protocols are represented in the `parsed` form, whereas non-recognised signals may be saved and re-transmitted as `raw` data.
Known protocols are represented in the `parsed` form, whereas non-recognized signals may be saved and re-transmitted as `raw` data.
#### Version history:
1. Initial version.
#### Format fields
| Name | Use | Type | Description |
| ---------- | ------- | ------ |------------ |
| name | both | string | Name of the button. Only printable ASCII characters are allowed. |
| type | both | string | Type of the signal. Must be `parsed` or `raw`. |
| protocol | parsed | string | Name of the infrared protocol. Refer to `ir` console command for the complete list of supported protocols. |
| address | parsed | hex | Payload address. Must be 4 bytes long. |
| command | parsed | hex | Payload command. Must be 4 bytes long. |
| frequency | raw | uint32 | Carrier frequency, in Hertz, usually 38000 Hz. |
| duty_cycle | raw | float | Carrier duty cycle, usually 0.33. |
| data | raw | uint32 | Raw signal timings, in microseconds between logic level changes. Individual elements must be space-separated. Maximum timings amount is 1024. |
| Name | Use | Type | Description |
| ---------- | ------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| name | both | string | Name of the button. Only printable ASCII characters are allowed. |
| type | both | string | Type of the signal. Must be `parsed` or `raw`. |
| protocol | parsed | string | Name of the infrared protocol. Refer to `ir` console command for the complete list of supported protocols. |
| address | parsed | hex | Payload address. Must be 4 bytes long. |
| command | parsed | hex | Payload command. Must be 4 bytes long. |
| frequency | raw | uint32 | Carrier frequency, in Hertz, usually 38000 Hz. |
| duty_cycle | raw | float | Carrier duty cycle, usually 0.33. |
| data | raw | uint32 | Raw signal timings, in microseconds between logic level changes. Individual elements must be space-separated. Maximum timings amount is 1024. |
## Infrared Library File Format
### Examples
- [TV Universal Library](/assets/resources/infrared/assets/tv.ir)
- [A/C Universal Library](/assets/resources/infrared/assets/ac.ir)
- [Audio Universal Library](/assets/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.\
It also has predefined button names for each universal library type, so that the universal remote application could understand them.
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.
### Version history:
1. Initial version.
## Infrared Test File Format
### Examples
See [Infrared Unit Tests](/assets/unit_tests/infrared/) for various examples.
### Description
Filename extension: `.irtest`
This file format is used to store technical test data that is too large to keep directly in the firmware.
@ -78,34 +90,38 @@ Known protocols are represented in the `parsed_array` form, whereas raw data has
Note: a single parsed signal must be represented as an array of size 1.
### Version history:
1. Initial version.
#### Format fields
| Name | Use | Type | Description |
| ---------- | ------------ | ------ |------------ |
| Name | Use | Type | Description |
| ---------- | ------------ | ------ | ---------------------------------------------------------------- |
| name | both | string | Name of the signal. Only printable ASCII characters are allowed. |
| type | both | string | Type of the signal. Must be `parsed_array` or `raw`. |
| count | parsed_array | uint32 | The number of parsed signals in an array. Must be at least 1. |
| protocol | parsed_array | string | Same as in previous formats. |
| address | parsed_array | hex | Ditto. |
| command | parsed_array | hex | Ditto. |
| repeat | parsed_array | bool | Indicates whether the signal is a repeated button press. |
| frequency | raw | uint32 | Same as in previous formats. |
| duty_cycle | raw | float | Ditto. |
| data | raw | uint32 | Ditto. |
| type | both | string | Type of the signal. Must be `parsed_array` or `raw`. |
| count | parsed_array | uint32 | The number of parsed signals in an array. Must be at least 1. |
| protocol | parsed_array | string | Same as in previous formats. |
| address | parsed_array | hex | Ditto. |
| command | parsed_array | hex | Ditto. |
| repeat | parsed_array | bool | Indicates whether the signal is a repeated button press. |
| frequency | raw | uint32 | Same as in previous formats. |
| duty_cycle | raw | float | Ditto. |
| data | raw | uint32 | Ditto. |
#### Signal names
The signal names in an `.irtest` file follow a convention `<name><test_number>`, where the name is one of:
- decoder_input
- decoder_expected
- encoder_decoder_input,
and the number is a sequential integer: 1, 2, 3...etc, which produces names like `decoder_input1`, `encoder_decoder_input3`, and so on.
and the number is a sequential integer: 1, 2, 3, etc., which produces names like `decoder_input1`, `encoder_decoder_input3`, and so on.
| Name | Type | Description |
| --------------------- | ------------ |-------------------------------------------------------------------------------------------------------|
| decoder_input | raw | A raw signal containing the decoder input. Is also used as the expected encoder output. |
| decoder_expected | parsed_array | An array of parsed signals containing the expected decoder output. Is also used as the encoder input. |
| --------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| decoder_input | raw | A raw signal containing the decoder input. Also used as the expected encoder output. |
| 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.

50
documentation/file_formats/LfRfidFileFormat.md
View File

@ -1,17 +1,19 @@
# LF RFID key file format
## Example
```
Filetype: Flipper RFID key
Version: 1
Key type: EM4100
Data: 01 23 45 67 89
```
## Description
Filename extension: `.rfid`
The file stores single RFID key of type defined by `Key type` parameter
The file stores a single RFID key of the type defined by the `Key type` parameter.
### Version history
@ -19,29 +21,29 @@ The file stores single RFID key of type defined by `Key type` parameter
### Format fields
|Name|Description|
|-|-|
|Key type|Key protocol type|
|Data|Key data (HEX values)|
| Name | Description |
| -------- | --------------------- |
| Key type | Key protocol type |
| Data | Key data (HEX values) |
### Supported key types
|Type|Full name|
|-|-|
|EM4100|EM-Micro EM4100|
|H10301|HID H10301|
|Idteck|IDTECK|
|Indala26|Motorola Indala26|
|IOProxXSF|Kantech IOProxXSF|
|AWID|AWID|
|FDX-A|FECAVA FDX-A|
|FDX-B|ISO FDX-B|
|HIDProx|Generic HIDProx|
|HIDExt|Generic HIDExt|
|Pyramid|Farpointe Pyramid|
|Viking|Viking|
|Jablotron|Jablotron|
|Paradox|Paradox|
|PAC/Stanley|PAC/Stanley|
|Keri|Keri|
|Gallagher|Gallagher|
| Type | Full name |
| ----------- | ----------------- |
| EM4100 | EM-Micro EM4100 |
| H10301 | HID H10301 |
| Idteck | IDTECK |
| Indala26 | Motorola Indala26 |
| IOProxXSF | Kantech IOProxXSF |
| AWID | AWID |
| FDX-A | FECAVA FDX-A |
| FDX-B | ISO FDX-B |
| HIDProx | Generic HIDProx |
| HIDExt | Generic HIDExt |
| Pyramid | Farpointe Pyramid |
| Viking | Viking |
| Jablotron | Jablotron |
| Paradox | Paradox |
| PAC/Stanley | PAC/Stanley |
| Keri | Keri |
| Gallagher | Gallagher |

22
documentation/file_formats/NfcFileFormats.md
View File

@ -19,9 +19,9 @@ This file format is used to store the UID, SAK and ATQA of a NFC-A device. It do
Version differences:
1. Initial version, deprecated
2. LSB ATQA (e.g. 4400 instead of 0044)
3. MSB ATQA (current version)
1. Initial version, deprecated
2. LSB ATQA (e.g. 4400 instead of 0044)
3. MSB ATQA (current version)
UID can be either 4 or 7 bytes long. ATQA is 2 bytes long. SAK is 1 byte long.
@ -68,13 +68,13 @@ This file format is used to store the UID, SAK and ATQA of a Mifare Ultralight/N
The "Signature" field contains the reply of the tag to the READ_SIG command. More on that can be found here: <https://www.nxp.com/docs/en/data-sheet/MF0ULX1.pdf> (page 31)
The "Mifare version" field is not related to the file format version, but to the Mifare Ultralight version. It contains the response of the tag to the GET_VERSION command. More on that can be found here: <https://www.nxp.com/docs/en/data-sheet/MF0ULX1.pdf> (page 21)
The "Mifare version" field is not related to the file format version but to the Mifare Ultralight version. It contains the response of the tag to the GET_VERSION command. More on that can be found here: <https://www.nxp.com/docs/en/data-sheet/MF0ULX1.pdf> (page 21)
Other fields are the direct representation of the card's internal state, more on them can be found in the same datasheet.
Other fields are the direct representation of the card's internal state. Learn more about them in the same datasheet.
Version differences:
1. Current version
1. Current version
## Mifare Classic
@ -126,7 +126,7 @@ This file format is used to store the NFC-A and Mifare Classic specific data of
Version differences:
1. Initial version, has Key A and Key B masks instead of marking unknown data with '??'.
1. Initial version, has Key A and Key B masks instead of marking unknown data with '??'.
Example:
@ -137,8 +137,8 @@ Example:
Key B map: 000000000000FFFF
# Mifare Classic blocks
...
2. Current version
2. Current version
## Mifare DESFire
@ -200,7 +200,7 @@ This file format is used to store the NFC-A and Mifare DESFire specific data of
hf mfdes write --aid 123456 --fid 01 -d 1337
Version differences:
None, there are no versions yet.
None, there are no versions yet.
## Mifare Classic Dictionary
@ -252,4 +252,4 @@ This file stores a list of EMV currency codes, country codes, or AIDs and their
Version differences:
1. Initial version
1. Initial version

116
documentation/file_formats/SubGhzFileFormats.md
View File

@ -2,7 +2,7 @@
## `.sub` File Format
Flipper uses `.sub` files to store SubGhz transmissions. They 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 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.
A `.sub` files consist of 3 parts:
@ -10,36 +10,36 @@ A `.sub` files consist of 3 parts:
- **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 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) for more details.
## Header Format
## Header format
Header is a mandatory part of `.sub` file. It contains file type, version, and frequency.
| Field | Type | Description |
| --- | --- | --- |
| `Filetype` | string | Filetype of subghz file format, must be `Flipper SubGhz Key File` |
| `Version` | uint | Version of subghz file format, current version is 1 |
| `Frequency` | uint | Frequency in Hertz |
| Field | Type | Description |
| ----------- | ------ | ----------------------------------------------------------------- |
| `Filetype` | string | Filetype of subghz file format, must be `Flipper SubGhz Key File` |
| `Version` | uint | Version of subghz file format, current version is 1 |
| `Frequency` | uint | Frequency in Hertz |
## Preset Information
## Preset information
Preset information is a mandatory part of `.sub` file. It contains preset type and, in case of custom preset, transceiver configuration data.
Preset information is a mandatory part for `.sub` files. It contains preset type and, in case of custom preset, transceiver configuration data.
When using one of the standard presets, only `Preset` field is required. When using custom preset, `Custom_preset_module` and `Custom_preset_data` fields are required.
When using one of the standard presets, only `Preset` field is required. When using a custom preset, `Custom_preset_module` and `Custom_preset_data` fields are required.
| Field | Description |
| --- | --- |
| `Preset` | Radio preset name (configures modulation, bandwidth, filters, etc.). When using a custom preset, must be `FuriHalSubGhzPresetCustom` |
| `Custom_preset_module` | Transceiver identifier, `CC1101` for Flipper Zero |
| `Custom_preset_data` | Transceiver configuration data |
| Field | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `Preset` | Radio preset name (configures modulation, bandwidth, filters, etc.). When using a custom preset, must be `FuriHalSubGhzPresetCustom` |
| `Custom_preset_module` | Transceiver identifier, `CC1101` for Flipper Zero |
| `Custom_preset_data` | Transceiver configuration data |
Built-in presets:
- `FuriHalSubGhzPresetOok270Async` - On/Off Keying, 270kHz bandwidth, async(IO throw GP0)
- `FuriHalSubGhzPresetOok650Async` - On/Off Keying, 650kHz bandwidth, async(IO throw GP0)
- `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)
- `FuriHalSubGhzPresetOok270Async` — On/Off Keying, 270kHz bandwidth, async(IO throw GP0)
- `FuriHalSubGhzPresetOok650Async` — On/Off Keying, 650kHz bandwidth, async(IO throw GP0)
- `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
@ -50,7 +50,7 @@ Transceiver configuration data is a string of bytes, encoded in hex format, sepa
- 00 00: marks register block end,
- `ZZ ZZ ZZ ZZ ZZ ZZ ZZ ZZ`: 8 byte PA table (Power amplifier ramp table).
More details can be found in [CC1101 datasheet](https://www.ti.com/lit/ds/symlink/cc1101.pdf) and `furi_hal_subghz` code.
You can find more details in the [CC1101 datasheet](https://www.ti.com/lit/ds/symlink/cc1101.pdf) and `furi_hal_subghz` code.
## File Data
@ -59,9 +59,9 @@ More details can be found in [CC1101 datasheet](https://www.ti.com/lit/ds/symlin
### Key Files
`.sub` files with key data files contain protocol name and its specific data, such as key value, bit length, etc.
Check out protocol registry for full list of supported protocol names.
Check out the protocol registry for the full list of supported protocol names.
Example of key data block in Princeton format:
Example of a key data block in Princeton format:
```
...
@ -74,7 +74,7 @@ TE: 400
Protocol-specific fields in this example:
| Field | Description |
| --- | --- |
| ----- | --------------------------------- |
| `Bit` | Princeton payload length, in bits |
| `Key` | Princeton payload data |
| `TE` | Princeton quantization interval |
@ -83,25 +83,23 @@ This file may contain additional fields, more details on available fields can be
### RAW Files
RAW `.sub` files contain raw signal data that is not processed through protocol-specific decoding. These files are useful for testing purposes, or for sending data that is not supported by any known protocol.
RAW `.sub` files contain raw signal data that is not processed through protocol-specific decoding. These files are useful for testing or sending data not supported by any known protocol.
For RAW files, 2 fields are required:
* `Protocol`, must be `RAW`
* `RAW_Data`, contains an array of timings, specified in micro seconds. 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.
- `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.
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.
Long payload not fitting into internal memory buffer and consisting of short duration timings (<10us) may not be read fast enough from SD Card. That might cause 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.
## File examples
## File Examples
### Key File, Standard Preset
### Key file, standard preset
Filetype: Flipper SubGhz Key File
Version: 1
@ -112,8 +110,7 @@ Long payload not fitting into internal memory buffer and consisting of short dur
Key: 00 00 00 00 00 95 D5 D4
TE: 400
### Key File, Custom Preset
### Key file, custom preset
Filetype: Flipper SubGhz Key File
Version: 1
@ -126,7 +123,7 @@ Long payload not fitting into internal memory buffer and consisting of short dur
Key: 00 00 00 00 00 95 D5 D4
TE: 400
### RAW File, Standard Preset
### RAW file, standard preset
Filetype: Flipper SubGhz RAW File
Version: 1
@ -137,7 +134,7 @@ Long payload not fitting into internal memory buffer and consisting of short dur
RAW_Data: -424 205 -412 159 -412 381 -240 181 ...
RAW_Data: -1448 361 -17056 131 -134 233 -1462 131 -166 953 -100 ...
### RAW File, Custom Preset
### RAW file, custom preset
Filetype: Flipper SubGhz RAW File
Version: 1
@ -150,26 +147,26 @@ Long payload not fitting into internal memory buffer and consisting of short dur
RAW_Data: -424 205 -412 159 -412 381 -240 181 ...
RAW_Data: -1448 361 -17056 131 -134 233 -1462 131 -166 953 -100 ...
# SubGhz Configuration Files
# SubGhz configuration files
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`.
### File Format
### File format
File contains a header and a list of manufacturer keys.
File header format:
| Field | Type | Description |
| --- | | --- |
| `Filetype` | string | SubGhz Keystore file format, always `Flipper SubGhz Keystore File` |
| `Version` | uint | File format version, 0 |
| `Encryption` | uint | File encryption: for user-provided file, set to 0 (disabled) |
| Field | Type | Description |
| ------------ | ------ | ------------------------------------------------------------------ |
| `Filetype` | string | SubGhz Keystore file format, always `Flipper SubGhz Keystore File` |
| `Version` | uint | File format version, 0 |
| `Encryption` | uint | File encryption: for user-provided file, set to 0 (disabled) |
Following the header, file contains a list of user-provided manufacture keys, one key per line.
For each key, a name and encryption method must be specified, according to comment in file header. More information can be found in keeloq decoder source code.
@ -186,7 +183,7 @@ For each key, a name and encryption method must be specified, according to comme
# - 2 - Normal_Learning
# - 3 - Secure_Learning
# - 4 - Magic_xor_type1 Learning
#
#
# NAME - name (string without spaces) max 64 characters long
Filetype: Flipper SubGhz Keystore File
Version: 0
@ -194,45 +191,44 @@ 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`.
### File Format
### File format
File contains a header, basic options, and optional lists of presets and frequencies.
Header must contain following fields:
Header must contain the following fields:
- `Filetype`: SubGhz setting file format, must be `Flipper SubGhz Setting File`.
- `Version`: file format version, current is `1`.
#### Basic Settings
#### Basic settings
- `Add_standard_frequencies`: bool, flag indicating whether to load standard frequencies shipped with firmware. If set to `false`, only frequencies specified in this file will be used.
- `Default_frequency`: uint, default frequency used in SubGhz application.
#### Adding More Frequencies
#### Adding more frequencies
- `Frequency`: uint — additional frequency for the subghz application frequency list. Used in Read and Read RAW. You can specify multiple frequencies, one per line.
#### Adding More Hopper Frequencies
#### Adding more hopper frequencies
- `Hopper_frequency`: uint — additional frequency for subghz application frequency hopping. Used in Frequency Analyzer. You can specify multiple frequencies, one per line.
Repeating same frequency will cause Flipper to listen on this frequency more often.
Repeating the same frequency will cause Flipper to listen to this frequency more often.
#### 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 following fields:
Each preset is defined by the following fields:
| Field | Description |
| --- | --- |
| `Custom_preset_name` | string, preset name that will be shown in SubGHz application |
| `Custom_preset_module` | string, transceiver identifier. Set to `CC1101` for Flipper Zero |
| `Custom_preset_data` | transceiver configuration data. See [Transceiver Configuration Data](#transceiver-configuration-data) for details. |
| Field | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `Custom_preset_name` | string, preset name that will be shown in SubGHz application |
| `Custom_preset_module` | string, transceiver identifier. Set to `CC1101` for Flipper Zero |
| `Custom_preset_data` | transceiver configuration data. See [Transceiver Configuration Data](#transceiver-configuration-data) for details. |
### Example
@ -252,7 +248,7 @@ Frequency: 300000000
Frequency: 310000000
Frequency: 320000000
# Frequencies used for hopping mode (keep this list small or flipper will miss signal)
# Frequencies used for hopping mode (keep this list small or Flipper will miss the signal)
Hopper_frequency: 300000000
Hopper_frequency: 310000000
Hopper_frequency: 310000000

12
documentation/file_formats/iButtonFileFormat.md
View File

@ -1,6 +1,7 @@
# iButton key file format
## Example
```
Filetype: Flipper iButton key
Version: 1
@ -9,11 +10,12 @@ Key type: Dallas
# Data size for Cyfral is 2, for Metakom is 4, for Dallas is 8
Data: 12 34 56 78 9A BC DE F0
```
## Description
Filename extension: `.ibtn`
The file stores single iButton key of type defined by `Key type` parameter
The file stores a single iButton key of the type defined by the `Key type` parameter.
### Version history
@ -21,7 +23,7 @@ The file stores single iButton key of type defined by `Key type` parameter
### Format fields
|Name|Description|
|-|-|
|Key type|Currently supported: Cyfral, Dallas, Metakom|
|Data|Key data (HEX values)|
| Name | Description |
| -------- | -------------------------------------------- |
| Key type | Currently supported: Cyfral, Dallas, Metakom |
| Data | Key data (HEX values) |