From 41c35cd59ec64296b41a5422ae1170c7dc4edfdb Mon Sep 17 00:00:00 2001 From: Ruslan Nadyrshin <110516632+rnadyrshin@users.noreply.github.com> Date: Tue, 8 Oct 2024 15:27:16 +0400 Subject: [PATCH] Documentation: update and cleanup (#3934) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Developers Docs editing * Logo underline removed The underline has been removed when hovering over the logo. * proofread docs * application -> app in several files --------- Co-authored-by: knrn64 <25254561+knrn64@users.noreply.github.com> Co-authored-by: あく --- ReadMe.md | 6 +- .../examples/example_number_input/ReadMe.md | 14 ++- documentation/AppManifests.md | 78 ++++++++-------- documentation/AppsOnSDCard.md | 42 ++++----- documentation/ExpansionModules.md | 8 +- documentation/FuriCheck.md | 20 ++-- documentation/FuriHalBus.md | 10 +- documentation/FuriHalDebuging.md | 14 +-- documentation/HardwareTargets.md | 12 +-- documentation/KeyCombo.md | 4 +- documentation/OTA.md | 2 +- documentation/UnitTests.md | 14 +-- documentation/UniversalRemotes.md | 4 +- .../Reading logs via the Dev Board.md | 4 +- documentation/doxygen/Doxyfile.cfg | 2 +- documentation/doxygen/app_publishing.dox | 7 ++ documentation/doxygen/applications.dox | 14 +-- documentation/doxygen/dev_board.dox | 6 +- documentation/doxygen/dev_tools.dox | 7 +- documentation/doxygen/examples.dox | 15 +-- documentation/doxygen/expansion_modules.dox | 2 +- documentation/doxygen/file_formats.dox | 1 + documentation/doxygen/header.html | 4 +- documentation/doxygen/index.dox | 28 +++--- documentation/doxygen/js.dox | 21 +++-- documentation/doxygen/misc.dox | 6 +- documentation/doxygen/system.dox | 16 ++-- documentation/fbt.md | 92 +++++++++---------- documentation/file_formats/NfcFileFormats.md | 2 +- .../file_formats/TarHeatshrinkFormat.md | 4 +- documentation/js/js_badusb.md | 2 +- documentation/js/js_data_types.md | 12 +-- documentation/js/js_math.md | 2 +- 33 files changed, 247 insertions(+), 228 deletions(-) create mode 100644 documentation/doxygen/app_publishing.dox diff --git a/ReadMe.md b/ReadMe.md index 15235e6fcf6..f16adc43289 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -9,8 +9,8 @@ # Flipper Zero Firmware - [Flipper Zero Official Website](https://flipperzero.one). A simple way to explain to your friends what Flipper Zero can do. -- [Flipper Zero Firmware Update](https://update.flipperzero.one). Improvements for your dolphin: latest firmware releases, upgrade tools for PC and mobile devices. -- [User Documentation](https://docs.flipperzero.one). Learn more about your dolphin: specs, usage guides, and anything you want to ask. +- [Flipper Zero Firmware Update](https://flipperzero.one/update). Improvements for your dolphin: latest firmware releases, upgrade tools for PC and mobile devices. +- [User Documentation](https://docs.flipper.net). Learn more about your dolphin: specs, usage guides, and anything you want to ask. - [Developer Documentation](https://developer.flipper.net/flipperzero/doxygen). Dive into the Flipper Zero Firmware source code: build system, firmware structure, and more. # Contributing @@ -19,7 +19,7 @@ Our main goal is to build a healthy and sustainable community around Flipper, so ## I need help -The best place to search for answers is our [User Documentation](https://docs.flipperzero.one). If you can't find the answer there, check our [Discord Server](https://flipp.dev/discord) or our [Forum](https://forum.flipperzero.one/). If you want to contribute to the firmware development, or modify it for your own needs, you can also check our [Developer Documentation](https://developer.flipper.net/flipperzero/doxygen). +The best place to search for answers is our [User Documentation](https://docs.flipper.net). If you can't find the answer there, check our [Discord Server](https://flipp.dev/discord) or our [Forum](https://forum.flipperzero.one/). If you want to contribute to the firmware development or modify it for your own needs, you can also check our [Developer Documentation](https://developer.flipper.net/flipperzero/doxygen). ## I want to report an issue diff --git a/applications/examples/example_number_input/ReadMe.md b/applications/examples/example_number_input/ReadMe.md index 9d5a0a9e5eb..8a221ba0870 100644 --- a/applications/examples/example_number_input/ReadMe.md +++ b/applications/examples/example_number_input/ReadMe.md @@ -1,7 +1,13 @@ -# Number Input +# Number Input {#example_number_input} -Simple keyboard that limits user inputs to a full number (integer). Useful to enforce correct entries without the need of intense validations after a user input. +Simple keyboard that limits user inputs to a full number (integer). Useful to enforce correct entries without the need for intense validations after a user input. -Definition of min/max values is required. Numbers are of type int32_t. If negative numbers are allowed withing min - max, an additional button is displayed to switch the sign between + and -. +## Source code -It is also possible to define a header text, shown in this example app with the 3 different input options. \ No newline at end of file +Source code for this example can be found [here](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/examples/example_number_input). + +## General principle + +Definition of min/max values is required. Numbers are of type int32_t. If negative numbers are allowed within min - max, an additional button is displayed to switch the sign between + and -. + +It is also possible to define a header text, as shown in this example app with the 3 different input options. \ No newline at end of file diff --git a/documentation/AppManifests.md b/documentation/AppManifests.md index 98a38ffd85f..f0f9d637991 100644 --- a/documentation/AppManifests.md +++ b/documentation/AppManifests.md @@ -1,65 +1,65 @@ -# Flipper Application Manifests (.fam) {#app_manifests} +# FAM (Flipper App Manifests) {#app_manifests} All components of Flipper Zero firmware — services, user applications, and system settings — are developed independently. Each component has a build system manifest file named `application.fam`, which defines the basic properties of that component and its relations to other parts of the system. -When building firmware, `fbt` collects all application manifests and processes their dependencies. Then it builds only those components referenced in the current build configuration. See [FBT docs](fbt.md) for details on build configurations. +When building firmware, `fbt` collects all app manifests and processes their dependencies. Then it builds only those components referenced in the current build configuration. See [FBT docs](fbt.md) for details on build configurations. -## Application definition +## App definition A firmware component's properties are declared in a Python code snippet, forming a call to the `App()` function with various parameters. -Only two parameters are mandatory: **appid** and **apptype**. Others are optional and may only be meaningful for certain application types. +Only two parameters are mandatory: **appid** and **apptype**. Others are optional and may only be meaningful for certain app types. ### Parameters -- **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. +- **appid**: string, app ID within the build system. It is used to specify which app to include in the build configuration and resolve dependencies and conflicts. - **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 | +| SYSTEM | App is not being shown in any menus. It can be started by other apps or from CLI | +| APP | Regular app for the main menu | +| PLUGIN | App to be built as a part of the firmware and to be placed in the Plugins menu | +| DEBUG | App 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 | +| SETTINGS | App 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 | +| EXTERNAL | App to be built as `.fap` plugin | +| METAPACKAGE | Does not define any code to be run, used for declaring dependencies and app 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. +- **entry_point**: C function to be used as the app'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. **For external applications**: specified definitions are used when building the application itself. -- **requires**: list of application IDs to include in the build configuration when the current application is referenced in the list of applications to build. -- **conflicts**: list of application IDs with which the current application conflicts. If any of them is found in the constructed application list, `fbt` will abort the firmware build process. +- **cdefines**: C preprocessor definitions to declare globally for other apps when the current app is included in the active build configuration. **For external apps**: specified definitions are used when building the app itself. +- **requires**: list of app IDs to include in the build configuration when the current app is referenced in the list of apps to build. +- **conflicts**: list of app IDs with which the current app conflicts. If any of them is found in the constructed app 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 `top` and `free` CLI commands to profile your app's memory usage._ +- **stack_size**: stack size in bytes to allocate for an app 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 `top` 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"]`. -- **resources**: name of a folder within the application's source folder to be used for packacking SD card resources for this application. They will only be used if application is included in build configuration. The default value is `""`, meaning no resources are packaged. +- **order**: order of an app 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 apps. +- **targets**: list of strings and target names with which this app is compatible. If not specified, the app is built for all targets. The default value is `["all"]`. +- **resources**: name of a folder within the app's source folder to be used for packacking SD card resources for this app. They will only be used if app is included in build configuration. The default value is `""`, meaning no resources are packaged. -#### Parameters for external applications +#### Parameters for external apps 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**. Paths starting with `"!"` are excluded from the list of sources. They can also include wildcard characters and directory names. For example, a value of `["*.c*", "!plugins"]` will include all C and C++ source files in the app folder except those in the `plugins` (and `lib`) folders. Paths with no wildcards (`*, ?`) are treated as full literal paths for both inclusion and exclusion. -- **fap_version**: string, application version. The default value is "0.1". You can also use a tuple of 2 numbers in the form of (x,y) to specify the version. It is also possible to add more dot-separated parts to the version, like patch number, but only major and minor version numbers are stored in the built .fap. +- **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. Apps cannot use the `"lib"` folder for their own source code, as it is reserved for **fap_private_libs**. Paths starting with `"!"` are excluded from the list of sources. They can also include wildcard characters and directory names. For example, a value of `["*.c*", "!plugins"]` will include all C and C++ source files in the app folder except those in the `plugins` (and `lib`) folders. Paths with no wildcards (`*, ?`) are treated as full literal paths for both inclusion and exclusion. +- **fap_version**: string, app version. The default value is "0.1". You can also use a tuple of 2 numbers in the form of (x,y) to specify the version. It is also possible to add more dot-separated parts to the version, like patch number, but only major and minor version numbers are stored in the built .fap. - **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_libs**: list of extra libraries to link the app 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) for details. -- **fap_extbuild**: provides support for parts of application sources to be built by external tools. Contains a list of `ExtFile(path="file name", command="shell command")` definitions. `fbt` will run the specified command for each file in the list. -- **fal_embedded**: boolean, default `False`. Applies only to PLUGIN type. If `True`, the plugin will be embedded into host application's .fap file as a resource and extracted to `apps_assets/APPID` folder on its start. This allows plugins to be distributed as a part of the host application. +- **fap_description**: string, may be empty. Short app description. +- **fap_author**: string, may be empty. App's author. +- **fap_weburl**: string, may be empty. App's homepage. +- **fap_icon_assets**: string. If present, it defines a folder name to be used for gathering image assets for this app. These images will be preprocessed and built alongside the app. See [FAP assets](AppsOnSDCard.md) for details. +- **fap_extbuild**: provides support for parts of app sources to be built by external tools. Contains a list of `ExtFile(path="file name", command="shell command")` definitions. `fbt` will run the specified command for each file in the list. +- **fal_embedded**: boolean, default `False`. Applies only to PLUGIN type. If `True`, the plugin will be embedded into host app's .fap file as a resource and extracted to `apps_assets/APPID` folder on its start. This allows plugins to be distributed as a part of the host app. -Note that commands are executed at the firmware root folder, and all intermediate files must be placed in an application's temporary build folder. For that, you can use pattern expansion by `fbt`: `${FAP_WORK_DIR}` will be replaced with the path to the application's temporary build folder, and `${FAP_SRC_DIR}` will be replaced with the path to the application's source folder. You can also use other variables defined internally by `fbt`. +Note that commands are executed at the firmware root folder, and all intermediate files must be placed in an app's temporary build folder. For that, you can use pattern expansion by `fbt`: `${FAP_WORK_DIR}` will be replaced with the path to the app's temporary build folder, and `${FAP_SRC_DIR}` will be replaced with the path to the app's source folder. You can also use other variables defined internally by `fbt`. Example for building an app from Rust sources: @@ -73,8 +73,8 @@ Example for building an app from Rust sources: ), ``` -- **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. +- **fap_private_libs**: list of additional libraries distributed as sources alongside the app. These libraries will be built as a part of the app build process. + Library sources must be placed in a subfolder of the `lib` folder within the app's source folder. Each library is defined as a call to the `Lib()` function, accepting the following parameters: - **name**: name of the library's folder. Required. @@ -82,7 +82,7 @@ Example for building an app from Rust sources: - **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 `[]`. + - **cincludes**: list of additional include paths to be used for building this library. Paths are relative to the app'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,14 +105,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 the `lib/loclass` folder. For the `mbedtls` library, `fbt` will add `lib/mbedtls/include` to the list of include paths for the application and compile only the files specified in the `sources` list. Additionally, `fbt` will enable `MBEDTLS_ERROR_C` preprocessor definition for `mbedtls` sources. -For the `loclass` library, `fbt` will add `lib/loclass` to the list of the include paths for the application and build all sources in that folder. Also, `fbt` will disable treating compiler warnings as errors for the `loclass` library, which can be useful when compiling large 3rd-party codebases. +For that snippet, `fbt` will build 2 libraries: one from sources in `lib/mbedtls` folder and another from sources in the `lib/loclass` folder. For the `mbedtls` library, `fbt` will add `lib/mbedtls/include` to the list of include paths for the app 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 included paths for the app 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. +Both libraries will be linked with the app. ## .fam file contents -The `.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 app definitions. For example, here's a part of `applications/service/bt/application.fam`: ```python App( diff --git a/documentation/AppsOnSDCard.md b/documentation/AppsOnSDCard.md index cb8106fc6cf..8bc73b1ab40 100644 --- a/documentation/AppsOnSDCard.md +++ b/documentation/AppsOnSDCard.md @@ -1,29 +1,29 @@ -# FAP (Flipper Application Package) {#apps_on_sd_card} +# FAP (Flipper App Package) {#apps_on_sd_card} -[fbt](./fbt.md) supports building applications as FAP files. FAPs are essentially `.elf` executables with extra metadata and resources bundled in. +[fbt](./fbt.md) supports building apps as FAP files. FAPs are essentially `.elf` executables with extra metadata and resources bundled in. 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 {#fap-howto} +## How to set up an app to be built as a FAP {#fap-howto} -FAPs are created and developed the same way as internal applications that are part of the firmware. +FAPs are created and developed the same way as internal apps that are part of the firmware. -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 app 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 app. Then configure its `application.fam` manifest, and set its `apptype` to `FlipperAppType.EXTERNAL`. See [Flipper App Manifests](AppManifests.md) 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, run `./fbt fap_{APPID}`, where APPID is your app's ID in its manifest. - To build your app and upload it over USB to run on Flipper, use `./fbt launch APPSRC=applications_user/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 an app without uploading it to Flipper, use `./fbt build APPSRC=applications_user/path/to/app`. This command is also available in VSCode configuration as "Build App". - 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. +FAPs can include static and animated images as private assets. They will be automatically compiled alongside app sources and can be referenced the same way as assets from the main firmware. -To use that feature, put your images in a subfolder inside your application's folder, then reference that folder in your application's manifest in the `fap_icon_assets` field. See [Application Manifests](AppManifests.md) for more details. +To use that feature, put your images in a subfolder inside your app's folder, then reference that folder in your app's manifest in the `fap_icon_assets` field. See [Flipper App Manifests](AppManifests.md) for more details. -To use these assets in your application, put `#include "{APPID}_icons.h"` in your application's source code, where `{APPID}` is the `appid` value field from your application's manifest. Then you can use all icons from your application's assets the same way as if they were a part of `assets_icons.h` of the main firmware. +To use these assets in your app, put `#include "{APPID}_icons.h"` in your app's source code, where `{APPID}` is the `appid` value field from your app's manifest. Then you can use all icons from your app's assets the same way as if they were a part of `assets_icons.h` of the main firmware. Images and animated icons should follow the same [naming convention](../assets/ReadMe.md) as those from the main firmware. @@ -33,11 +33,11 @@ Images and animated icons should follow the same [naming convention](../assets/R 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. -If debugging session is active, firmware will trigger a breakpoint after loading a FAP it into memory, but before running any code from it. This allows you to set breakpoints in the FAP's code. Note that any breakpoints set before the FAP is loaded may need re-setting after the FAP is actually loaded, since before loading it debugger cannot know the exact address of the FAP's code. +If debugging session is active, firmware will trigger a breakpoint after loading a FAP into memory, but before running any code from it. This allows you to set breakpoints in the FAP's code. Note that any breakpoints set before the FAP is loaded may need re-setting after the FAP is actually loaded, since the debugger cannot know the exact address of the FAP's code before loading the FAP. ### Setting up debugging environment -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. +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) for details. To debug FAPs, do the following: @@ -45,23 +45,23 @@ To debug FAPs, do the following: 2. Flash it with `./fbt flash` 3. [Build your FAP](#fap-howto) and run it on Flipper -After that, you can attach with `./fbt debug` or VS Code and use all debug features. +After that, you can attach the debugger to the target MCU 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 the matching firmware folder is linked as `build/latest`. Otherwise, debugging will not work. +It is **important** that firmware and app 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 app from an 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 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. -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 the 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. -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. +Apps 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 app's major API version matches the 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. +The App Loader allocates memory for the app and copies it to RAM, processing relocations and providing concrete addresses for imported symbols using the [symbol table](#symbol-table). Then it starts the app. ## API versioning {#api-versioning} -Not all parts of firmware are available for external applications. A subset of available functions and variables is defined in the "api_symbols.csv" file, which is a part of the firmware target definition in the `targets/` directory. +Not all parts of firmware are available for external apps. A subset of available functions and variables is defined in the "api_symbols.csv" file, which is a part of the firmware target definition in the `targets/` directory. `fbt` uses semantic versioning for the API. The major version is incremented when there are breaking changes in the API. The minor version is incremented when new features are added. @@ -78,6 +78,6 @@ API versioning is mostly automated by `fbt`. When rebuilding the firmware, `fbt` ### Symbol table {#symbol-table} -The symbol table is a list of symbols exported by firmware and available for external applications. It is generated by `fbt` from the API symbols file and is used by the App Loader to resolve addresses of imported symbols. It is build as a part of the `fap_loader` application. +The symbol table is a list of symbols exported by firmware and available for external apps. 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` app. -`fbt` also checks if all imported symbols are present in the symbol table. If there are any missing symbols, it will issue a warning listing them. The application won't be able to run on the device until all required symbols are provided in the symbol table. +`fbt` also checks if all imported symbols are present in the symbol table. If there are any missing symbols, it will issue a warning listing them. The app won't be able to run on the device until all required symbols are provided in the symbol table. diff --git a/documentation/ExpansionModules.md b/documentation/ExpansionModules.md index fd9703adcc4..2fbdb738f8b 100644 --- a/documentation/ExpansionModules.md +++ b/documentation/ExpansionModules.md @@ -29,7 +29,7 @@ Depending on the UART selected for communication, the following pins area availa ## Frame structure -Each frame consists of a header (1 byte), contents (size depends of frame type) and checksum (1 byte) fields: +Each frame consists of a header (1 byte), contents (size depends on frame type) and checksum (1 byte) fields: | Header (1 byte) | Contents (0 or more bytes) | Checksum (1 byte) | |-----------------|----------------------------|-------------------| @@ -79,7 +79,7 @@ CONTROL frames are used to control various aspects of the communication and enab |-----------------|-------------------|-------------------| | 0x04 | Command | XOR checksum | -The `Command` field SHALL have one of the followind values: +The `Command` field SHALL have one of the following values: | Command | Meaning | Note | |---------|--------------------------|:----:| @@ -96,7 +96,7 @@ Notes: ### Data frame -DATA frames are used to transmit arbitrary data in either direction. Each DATA frame can hold up to 64 bytes. If an RPC session is curretly open, all received bytes are forwarded to it. +DATA frames are used to transmit arbitrary data in either direction. Each DATA frame can hold up to 64 bytes. If an RPC session is currently open, all received bytes are forwarded to it. | Header (1 byte) | Contents (1 to 65 byte(s)) | Checksum (1 byte) | |-----------------|----------------------------|-------------------| @@ -110,7 +110,7 @@ The `Data` field SHALL have the following structure: ## Communication flow -In order for the host to be able to detect the module, the respective feature must be enabled first. This can be done via the GUI by going to `Settings -> Expansion Modules` and selecting the required `Listen UART` or programmatically by calling `expansion_enable()`. Likewise, disabling this feature via the same GUI or by calling `expansion_disable()` will result in ceasing all communications and not being able to detect any connected modules. +In order for the host to be able to detect the module, the respective feature must be enabled first. This can be done via the GUI by going to `Settings → Expansion Modules` and selecting the required `Listen UART` or programmatically by calling `expansion_enable()`. Likewise, disabling this feature via the same GUI or by calling `expansion_disable()` will result in ceasing all communications and not being able to detect any connected modules. The communication is always initiated by the module by the means of shortly pulling the RX pin down. The host SHALL respond with a HEARTBEAT frame indicating that it is ready to receive requests. The module then MUST issue a BAUDRATE request within Tto. Failure to do so will result in the host dropping the connection and returning to its initial state. diff --git a/documentation/FuriCheck.md b/documentation/FuriCheck.md index 77a44ca84bf..ead964af972 100644 --- a/documentation/FuriCheck.md +++ b/documentation/FuriCheck.md @@ -1,13 +1,13 @@ # Run time checks and forced system crash {#furi_check} The best way to protect system integrity is to reduce amount cases that we must handle and crash the system as early as possible. -For that purpose we have bunch of helpers located in Furi Core check.h. +For that purpose, we have a bunch of helpers located in Furi Core `check.h`. ## Couple notes before start -- Definition of Crash - log event, save crash information in RTC and reboot the system. -- Definition of Halt - log event, stall the system. -- Debug and production builds behaves differently: debug build will never reset system in order to preserve state for debugging. +- Definition of Crash — log event, save crash information in RTC and reboot the system. +- Definition of Halt — log event, stall the system. +- Debug and production builds behave differently: debug build will never reset system in order to preserve state for debugging. - If you have debugger connected we will stop before reboot automatically. - All helpers accept optional MESSAGE_CSTR: it can be in RAM or Flash memory, but only messages from Flash will be shown after system reboot. - MESSAGE_CSTR can be NULL, but macros magic already doing it for you, so just don't. @@ -16,10 +16,10 @@ For that purpose we have bunch of helpers located in Furi Core check.h. Assert condition in development environment and crash the system if CONDITION is false. -- Should be used at development stage in apps and services -- Keep in mind that release never contains this check -- Keep in mind that libraries never contains this check by default, use `LIB_DEBUG=1` if you need it -- Avoid putting function calls into CONDITION, since it may be omitted in some builds +- Should be used at development stage in apps and services. +- Keep in mind that release never contains this check. +- Keep in mind that libraries never contain this check by default, use `LIB_DEBUG=1` if you need it. +- Avoid putting function calls into CONDITION, since it may be omitted in some builds. ## `furi_check(CONDITION)` or `furi_check(CONDITION, MESSAGE_CSTR)` @@ -31,10 +31,10 @@ Always assert condition and crash the system if CONDITION is false. Crash the system. -- Use it to crash the system. For example: if abnormal condition detected. +- Use it to crash the system. For example, if an abnormal condition is detected. ## `furi_halt()` or `furi_halt(MESSAGE_CSTR)` Halt the system. -- We use it internally to shutdown flipper if poweroff is not possible. +- We use it internally to shutdown Flipper if poweroff is not possible. diff --git a/documentation/FuriHalBus.md b/documentation/FuriHalBus.md index 12c5a70ece1..5e7bb5f402f 100644 --- a/documentation/FuriHalBus.md +++ b/documentation/FuriHalBus.md @@ -5,7 +5,7 @@ On system startup, most of the peripheral devices are under reset and not clocked by default. This is done to reduce power consumption and to guarantee that the device will always be in the same state before use. Some crucial peripherals are enabled right away by the system, others must be explicitly enabled by the user code. -**NOTE:** Here and afterwards the word *"system"* refers to any code belonging to the operating system, hardware drivers or built-in applications. +**NOTE:** Here and afterwards, the word *"system"* refers to any code belonging to the operating system, hardware drivers or built-in apps. To **ENABLE** a peripheral, call `furi_hal_bus_enable()`. At the time of the call, the peripheral in question MUST be disabled, otherwise a crash will occur to indicate improper use. This means that any given peripheral cannot be enabled twice or more without disabling it first. @@ -24,7 +24,7 @@ Built-in peripherals are divided into three categories: Below is the list of peripherals that are enabled by the system. The user code must NEVER attempt to disable them. If a corresponding API is provided, the user code must employ it in order to access the peripheral. -*Table 1* - Peripherals enabled by the system +*Table 1* — Peripherals enabled by the system | Peripheral | Enabled at | | :-----------: | :-----------------------: | @@ -49,7 +49,7 @@ Below is the list of peripherals that are enabled and disabled by the system. Th When not using the API, these peripherals MUST be enabled by the user code and then disabled when not needed anymore. -*Table 2* - Peripherals enabled and disabled by the system +*Table 2* — Peripherals enabled and disabled by the system | Peripheral | API header file | | :-----------: | :-------------------: | @@ -69,7 +69,7 @@ Below is the list of peripherals that are not enabled by default and MUST be ena Note that some of these peripherals may also be used by the system to implement its certain features. The system will take over any given peripheral only when the respective feature is in use. -*Table 3* - Peripherals enabled and disabled by user +*Table 3* — Peripherals enabled and disabled by user | Peripheral | System | Purpose | | :-----------: | :-------: | ------------------------------------- | @@ -93,7 +93,7 @@ The DMA1,2 peripherals are a special case in that they have multiple independent Below is the list of DMA channels and their usage by the system. -*Table 4* - DMA channels +*Table 4* — DMA channels | DMA | Channel | System | Purpose | | :---: | :-------: | :-------: | ------------------------- | diff --git a/documentation/FuriHalDebuging.md b/documentation/FuriHalDebuging.md index 5104a999829..bc7d532d21b 100644 --- a/documentation/FuriHalDebuging.md +++ b/documentation/FuriHalDebuging.md @@ -1,7 +1,7 @@ # Furi HAL Debugging {#furi_hal_debugging} -Some Furi subsystems got additional debugging features that can be enabled by adding additional defines to firmware compilation. -Usually they are used for low level tracing and profiling or signal redirection/duplication. +Some Furi subsystems have additional debugging features that can be enabled by adding additional defines to firmware compilation. +Usually, they are used for low level tracing and profiling or signal redirection/duplication. ## FuriHalOs @@ -10,9 +10,9 @@ Usually they are used for low level tracing and profiling or signal redirection/ There are 3 signals that will be exposed to external GPIO pins: -- `AWAKE` - `PA7` - High when system is busy with computations, low when sleeping. Can be used to track transitions to sleep mode. -- `TICK` - `PA6` - Flipped on system tick, only flips when no tick suppression in progress. Can be used to track tick skew and abnormal task scheduling. -- `SECOND` - `PA4` - Flipped each second. Can be used for tracing RT issue: time flow disturbance means system doesn't conforms Hard RT. +- `AWAKE` — `PA7` — High when system is busy with computations, low when sleeping. Can be used to track transitions to sleep mode. +- `TICK` — `PA6` — Flipped on system tick, only flips when no tick suppression in progress. Can be used to track tick skew and abnormal task scheduling. +- `SECOND` — `PA4` — Flipped each second. Can be used for tracing RT issue: time flow disturbance means system doesn't conform Hard RT. @@ -22,8 +22,8 @@ There are 3 signals that will be exposed to external GPIO pins: There are 2 signals that will be exposed to external GPIO pins: -- `WFI` - `PB2` - Light sleep (wait for interrupt) used. Basically this is lightest and most non-breaking things power save mode. All function and debug should work correctly in this mode. -- `STOP` - `PC3` - STOP mode used. Platform deep sleep mode. Extremely fragile mode where most of the silicon is disabled or in unusable state. Debugging MCU in this mode is nearly impossible. +- `WFI` — `PB2` — Light sleep (wait for interrupt) used. Basically, this is the lightest and most non-breaking things power save mode. All functions and debug should work correctly in this mode. +- `STOP` — `PC3` — STOP mode used. Platform deep sleep mode. Extremely fragile mode where most of the silicon is disabled or in unusable state. Debugging MCU in this mode is nearly impossible. ## FuriHalSD diff --git a/documentation/HardwareTargets.md b/documentation/HardwareTargets.md index 9c36088eac8..e35ee7991b1 100644 --- a/documentation/HardwareTargets.md +++ b/documentation/HardwareTargets.md @@ -25,20 +25,20 @@ A target definition file, `target.json`, is a JSON file that can contain the fol * `excluded_modules`: list of strings specifying fbt library (module) names to exclude from being used to configure build environment. -## Applications & Hardware +## Apps & Hardware -Not all applications are available on different hardware targets. +Not all apps are available on different hardware targets. -* For applications built into the firmware, you have to specify a compatible application set using `FIRMWARE_APP_SET=...` fbt option. See [fbt docs](./fbt.md) for details on build configurations. +* For apps built into the firmware, you have to specify a compatible app set using `FIRMWARE_APP_SET=...` fbt option. See [fbt docs](./fbt.md) for details on build configurations. -* For applications built as external .faps, you have to explicitly specify compatible targets in application's manifest, `application.fam`. For example, to limit application to a single target, add `targets=["f7"],` to the manifest. It won't be built for other targets. +* For apps built as external FAPs, you have to explicitly specify compatible targets in the app's manifest, `application.fam`. For example, to limit the app to a single target, add `targets=["f7"],` to the manifest. It won't be built for other targets. -For details on application manifests, check out [their docs page](./AppManifests.md). +For details on app manifests, check out [their docs page](./AppManifests.md). ## Building Firmware for a Specific Target -You have to specify TARGET_HW (and, optionally, FIRMWARE_APP_SET) for `fbt` to build firmware for non-default target. For example, building and flashing debug firmware for f18 can be done with +You have to specify TARGET_HW (and, optionally, FIRMWARE_APP_SET) for `fbt` to build firmware for a non-default target. For example, building and flashing debug firmware for f18 can be done with ./fbt TARGET_HW=18 flash_usb_full diff --git a/documentation/KeyCombo.md b/documentation/KeyCombo.md index e3c5e000432..09bbb1ee0bd 100644 --- a/documentation/KeyCombo.md +++ b/documentation/KeyCombo.md @@ -10,7 +10,7 @@ There are times when your Flipper feels blue and doesn't respond to any of your - Release `LEFT` and `BACK` This combo performs a hardware reset by pulling the MCU reset line down. -Main components involved: Keys -> DD8(NC7SZ32M5X, OR-gate) -> DD1(STM32WB55, MCU). +Main components involved: Keys → DD8(NC7SZ32M5X, OR-gate) → DD1(STM32WB55, MCU). It won't work only in one case: @@ -26,7 +26,7 @@ It won't work only in one case: - 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). It won't work only in one case: diff --git a/documentation/OTA.md b/documentation/OTA.md index 9783a704770..1499ab74b6a 100644 --- a/documentation/OTA.md +++ b/documentation/OTA.md @@ -2,7 +2,7 @@ ## Executing code from RAM -In Flipper firmware, we have a special boot mode that loads a specially crafted system image into RAM and transfers control to it. System image executing in RAM has full write access to Flipper's entire flash memory — something that's not possible when running main code from the same flash. +In Flipper firmware, we have a special boot mode that loads a specially crafted system image into RAM and transfers control to it. The 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. diff --git a/documentation/UnitTests.md b/documentation/UnitTests.md index b77cd56c6ec..5c80e763d4f 100644 --- a/documentation/UnitTests.md +++ b/documentation/UnitTests.md @@ -5,7 +5,7 @@ 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](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests). +Flipper Zero firmware includes a separate app called [unit_tests](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests). It is run directly on Flipper devices in order to employ their hardware features and rule out any platform-related differences. When contributing code to the Flipper Zero firmware, it is highly desirable to supply unit tests along with the proposed features. @@ -28,13 +28,13 @@ See [test_index.c](https://github.com/flipperdevices/flipperzero-firmware/blob/d #### Entry point -The common entry point for all tests is the [unit_tests](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests) application. Test-specific code is placed into an arbitrarily named subdirectory and is then called from the [test_index.c](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests/test_index.c) source file. +The common entry point for all tests is the [unit_tests](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests) app. Test-specific code is placed into an arbitrarily named subdirectory and is then called from the [test_index.c](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests/test_index.c) source file. #### Test assets Some unit tests require external data in order to function. These files (commonly called assets) reside in the [unit_tests](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/debug/unit_tests/resources/unit_tests) directory in their respective subdirectories. Asset files can be of any type (plain text, FlipperFormat (FFF), binary, etc.). -### Application-specific +### App-specific #### Infrared @@ -50,9 +50,9 @@ To add unit tests for your protocol, follow these steps: 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. +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. 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. @@ -61,4 +61,4 @@ Decoded data is represented in arrays (since a single raw signal may be decoded ##### 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. +Recording raw IR signals is possible using Flipper Zero. Launch the CLI session, run `ir rx raw`, then point the remote towards the Flipper's receiver and send the signals. The raw signal data will be printed to the console in a convenient format. diff --git a/documentation/UniversalRemotes.md b/documentation/UniversalRemotes.md index 360d8a0abb2..65f64526fbc 100644 --- a/documentation/UniversalRemotes.md +++ b/documentation/UniversalRemotes.md @@ -41,11 +41,11 @@ When the user presses a button, a whole set of parameters is transmitted to the 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. +1. Get the remote and press the **POWER** button so that the display shows that A/C is ON. 2. Set the A/C to the corresponding mode (see table below), leaving other parameters such as fan speed or vane on **AUTO** (if applicable). 3. Press the **POWER** button to switch the A/C off. 4. Start learning a new remote on Flipper if it's the first button or press `+` to add a new button otherwise. -5. Point the remote to Flipper's IR receiver as directed and press **POWER** button once again. +5. Point the remote to Flipper's IR receiver as directed and press the **POWER** button once again. 6. Save the resulting signal under the specified name. 7. Repeat steps 2-6 for each signal from the table below. diff --git a/documentation/devboard/Reading logs via the Dev Board.md b/documentation/devboard/Reading logs via the Dev Board.md index e9fc0e2ca8f..c2daf83aced 100644 --- a/documentation/devboard/Reading logs via the Dev Board.md +++ b/documentation/devboard/Reading logs via the Dev Board.md @@ -8,7 +8,7 @@ The Developer Board allows you to read Flipper Zero logs via UART. Unlike readin ## Setting the log level -Depending on your needs, you can set the log level by going to **Main Menu -> Settings -> Log Level**. To learn more about logging levels, visit [Settings](https://docs.flipperzero.one/basics/settings#d5TAt). +Depending on your needs, you can set the log level by going to **Main Menu → Settings → Log Level**. To learn more about logging levels, visit [Settings](https://docs.flipperzero.one/basics/settings#d5TAt). ![You can manually set the preferred log level](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/INzQMw8QUsG9PXi30WFS0_monosnap-miro-2023-07-11-13-29-47.jpg) @@ -145,7 +145,7 @@ On Windows, do the following: 3. Connect the developer board to your computer using a USB Type-C cable. ![Connect the developer board with a USB-C cable](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/iPpsMt2-is4aIjiVeFu5t_hjxs2i1oovrnps74v5jgsimage.png) -4. Find the serial port that the developer board is connected to by going to **Device Manager -> Ports (COM & LPT)** and looking for a new port that appears when you connect the Wi-Fi developer board. +4. Find the serial port that the developer board is connected to by going to **Device Manager → Ports (COM & LPT)** and looking for a new port that appears when you connect the Wi-Fi developer board. ![Find the serial port in your Device Manager](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/KKLQJK1lvqmI5iab3d__C_image.png) 5. Run the PuTTY application and select **Serial** as the connection type. diff --git a/documentation/doxygen/Doxyfile.cfg b/documentation/doxygen/Doxyfile.cfg index a7838163b0d..90f36415f15 100644 --- a/documentation/doxygen/Doxyfile.cfg +++ b/documentation/doxygen/Doxyfile.cfg @@ -42,7 +42,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "Flipper Zero Firmware" +PROJECT_NAME = "Flipper Developer Docs" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version diff --git a/documentation/doxygen/app_publishing.dox b/documentation/doxygen/app_publishing.dox new file mode 100644 index 00000000000..747891221ee --- /dev/null +++ b/documentation/doxygen/app_publishing.dox @@ -0,0 +1,7 @@ +/** +@page app_publishing Publishing to the Apps Catalog + +You can publish your app in the Flipper Apps Catalog. Users will be able to download your app and install it on their Flipper Zero via [mobile apps](https://flpr.app/) and [Flipper Lab](https://lab.flipper.net/apps). Check out the documentation below: + +- [Apps Catalog: Contribution Guide](https://github.com/flipperdevices/flipper-application-catalog/blob/main/documentation/Contributing.md) — How to publish and update your app in the Apps Catalog +*/ diff --git a/documentation/doxygen/applications.dox b/documentation/doxygen/applications.dox index ad0dfba8d80..7c21a6e8d95 100644 --- a/documentation/doxygen/applications.dox +++ b/documentation/doxygen/applications.dox @@ -1,12 +1,12 @@ /** -@page applications Application Programming +@page applications App Development -Flipper Zero features full support for custom applications which (usually) do not require any changes to the firmware. +Flipper Zero features full support for custom apps which (usually) do not require any changes to the firmware. -For easy application development, a software tool called [uFBT](https://github.com/flipperdevices/flipperzero-ufbt) is available. +For easy app development, a software tool called [uFBT](https://github.com/flipperdevices/flipperzero-ufbt) is available. -- @subpage vscode - Flipper Zero integration for VS Code -- @subpage apps_on_sd_card - Creating apps that can be dynamically loaded from the SD card -- @subpage app_manifests - How applications announce themselves to the system -- @subpage app_examples - Various application examples, complete with the source code +- @subpage apps_on_sd_card — Creating apps that can be dynamically loaded from the SD card +- @subpage app_manifests — How apps announce themselves to the system +- @subpage app_examples — Various app examples, complete with the source code +- @subpage app_publishing — Learn how to publish and update your app in the Apps Catalog */ diff --git a/documentation/doxygen/dev_board.dox b/documentation/doxygen/dev_board.dox index f9363ed0690..6caa44c7050 100644 --- a/documentation/doxygen/dev_board.dox +++ b/documentation/doxygen/dev_board.dox @@ -3,8 +3,8 @@ [ESP32-based development board](https://shop.flipperzero.one/collections/flipper-zero-accessories/products/wifi-devboard). -- @subpage dev_board_get_started - Quick start for new users -- @subpage dev_board_reading_logs - Find out what is currently happening on the system -- @subpage dev_board_fw_update - Keep the developer board up to date +- @subpage dev_board_get_started — Quick start for new users +- @subpage dev_board_reading_logs — Find out what is currently happening on the system +- @subpage dev_board_fw_update — Keep the developer board up to date */ diff --git a/documentation/doxygen/dev_tools.dox b/documentation/doxygen/dev_tools.dox index bd7a5c704fc..e3c589faced 100644 --- a/documentation/doxygen/dev_tools.dox +++ b/documentation/doxygen/dev_tools.dox @@ -3,7 +3,8 @@ Hardware and software tools for all kinds of programming. -- @subpage fbt - Official build and deployment tool for Flipper Zero -- @subpage dev_board - ESP32-based development board -- @subpage ota_updates - Standalone firmware self-update mechanism +- @subpage fbt — Official build and deployment tool for Flipper Zero +- @subpage vscode — Flipper Zero integration for VS Code +- @subpage dev_board — ESP32-based development board +- @subpage ota_updates — Standalone firmware self-update mechanism */ diff --git a/documentation/doxygen/examples.dox b/documentation/doxygen/examples.dox index 9743549a2df..43039d2f700 100644 --- a/documentation/doxygen/examples.dox +++ b/documentation/doxygen/examples.dox @@ -1,10 +1,13 @@ /** -@page app_examples Application Examples +@page app_examples App Examples -A collection of examples covering various aspects of application programming for Flipper Zero. +A collection of examples covering various aspects of app development for Flipper Zero. -- @subpage example_app_images - Using images and icons in an application -- @subpage example_app_assets - Using application-specific asset folders -- @subpage example_app_data - Using application-specific data folders -- @subpage example_thermo - Reading data from a 1-Wire thermometer +- @subpage example_number_input — Using a simple keyboard that limits user inputs to a full number (integer) +- @subpage example_app_images — Using images and icons in an app +- @subpage example_app_assets — Using app-specific asset folders +- @subpage example_app_data — Using app-specific data folders +- @subpage example_thermo — Reading data from a 1-Wire thermometer + +You can find more app examples in the [repository on GitHub](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/examples). */ diff --git a/documentation/doxygen/expansion_modules.dox b/documentation/doxygen/expansion_modules.dox index c38bb2923f6..5e9731b0212 100644 --- a/documentation/doxygen/expansion_modules.dox +++ b/documentation/doxygen/expansion_modules.dox @@ -3,6 +3,6 @@ Expansion modules are special pieces of hardware designed to interface with Flipper's GPIO connector, such as the [Video Game Module](https://shop.flipperzero.one/collections/flipper-zero-accessories/products/video-game-module-for-flipper-zero). -- @subpage expansion_protocol - Transport protocol for smart expansion modules +- @subpage expansion_protocol — Transport protocol for smart expansion modules */ diff --git a/documentation/doxygen/file_formats.dox b/documentation/doxygen/file_formats.dox index 47c2362cf75..2ec780d010d 100644 --- a/documentation/doxygen/file_formats.dox +++ b/documentation/doxygen/file_formats.dox @@ -9,5 +9,6 @@ Descriptions of various file formats used in Flipper Zero, grouped by applicatio - @subpage lfrfid_file_format - @subpage nfc_file_format - @subpage subghz_file_format +- @subpage heatshrink_file_format */ diff --git a/documentation/doxygen/header.html b/documentation/doxygen/header.html index cd3ea49e75b..5cc0aba38f3 100644 --- a/documentation/doxygen/header.html +++ b/documentation/doxygen/header.html @@ -48,11 +48,11 @@ - Logo + Logo -
$projectname $projectnumber +
$projectname $projectnumber
$projectbrief
diff --git a/documentation/doxygen/index.dox b/documentation/doxygen/index.dox index 78055caad04..7bd9024a116 100644 --- a/documentation/doxygen/index.dox +++ b/documentation/doxygen/index.dox @@ -1,26 +1,26 @@ /** @mainpage Overview -Welcome to the Flipper Zero Firmware Developer Documentation! +Welcome to the Flipper Developer Documentation! -This documentation is intended for developers who want to modify the firmware of the Flipper Zero. +This documentation is intended for developers interested in modifying the Flipper Zero firmware, creating Apps and JavaScript programs, or working on external hardware modules for the device. -If you are looking for the user manual, please visit the [User Documentation](https://docs.flipperzero.one/) instead. +If you are looking for the user manual, please visit the [User Documentation](https://docs.flipper.net/) instead. -The documentation is divided into several sections, with all of them accessible from the sidebar on the left: +The documentation is divided into several sections. All of them are accessible from the sidebar on the left: -- @ref applications - Writing applications for Flipper Zero -- @ref system - Understanding the firmware's internals -- @ref file_formats - Saving and loading data to and from files -- @ref dev_tools - Hardware and software tools for all kinds of programming -- @ref expansion - Additional modules to expand Flipper's consciousness -- @ref misc - Various useful pieces of information -- @ref js - JS-based scripting engine documentation +- @ref dev_tools — Hardware and software tools for all kinds of programming +- @ref system — Understanding the firmware's internals +- @ref applications — Developing apps for Flipper Zero +- @ref js — JS-based scripting engine +- @ref expansion — Additional modules to expand Flipper's consciousness +- @ref file_formats — Saving and loading data to and from files +- @ref misc — Various useful pieces of information -Aside from the manually-written documentation files, there's also a few automatically-generated ones at the bottom of the sidebar: +These sections are all manually written. There are also a few automatically generated ones at the bottom of the sidebar: -- [Data Structures](annotated.html) - Every data structure in a list -- [Files](files.html) - Source file tree with easy navigation +- [Data Structures](annotated.html) — Every data structure in a list +- [Files](files.html) — Source file tree with easy navigation These are generated from the source code and are useful for quickly finding the source code or API documentation for a particular function or data structure. */ diff --git a/documentation/doxygen/js.dox b/documentation/doxygen/js.dox index f4faf668fea..33ac078d923 100644 --- a/documentation/doxygen/js.dox +++ b/documentation/doxygen/js.dox @@ -1,21 +1,22 @@ /** @page js JavaScript -This page contains some information on the Flipper Zero scripting engine, which is based on a modified mJS library +This page contains some information on the Flipper Zero scripting engine, which is based on a modified mJS library. - [Brief mJS description](https://github.com/cesanta/mjs/blob/master/README.md) - @subpage js_data_types - @subpage js_builtin -JavaScript Modules -JS modules use the Flipper app plugin system. Each module is compiled into a .fal library file and is located on a microSD card. Here is a list of implemented modules: +## JavaScript modules -- @subpage js_badusb - BadUSB module -- @subpage js_serial - Serial module -- @subpage js_math - Math module -- @subpage js_dialog - Dialog module -- @subpage js_submenu - Submenu module -- @subpage js_textbox - Textbox module -- @subpage js_notification - Notifications module +JS modules use the Flipper app plugin system. Each module is compiled into a `.fal` library file and is located on a microSD card. Here is a list of implemented modules: + +- @subpage js_badusb — BadUSB module +- @subpage js_serial — Serial module +- @subpage js_math — Math module +- @subpage js_dialog — Dialog module +- @subpage js_submenu — Submenu module +- @subpage js_textbox — Textbox module +- @subpage js_notification — Notifications module */ diff --git a/documentation/doxygen/misc.dox b/documentation/doxygen/misc.dox index 0ef232ba249..f49a9524ab3 100644 --- a/documentation/doxygen/misc.dox +++ b/documentation/doxygen/misc.dox @@ -3,7 +3,7 @@ Various pieces of information that do not fall into other categories. -- @subpage lfrfid_raw - Collecting raw data from LFRFID tags -- @subpage key_combos - Different key combination shortcuts for Flipper Zero -- @subpage universal_remotes - Creating and improving IR universal remote libraries +- @subpage lfrfid_raw — Collecting raw data from LF RFID tags +- @subpage key_combos — Different key combination shortcuts for Flipper Zero +- @subpage universal_remotes — Creating and improving IR universal remote libraries */ diff --git a/documentation/doxygen/system.dox b/documentation/doxygen/system.dox index 328717ea21e..d7e42ed4fd1 100644 --- a/documentation/doxygen/system.dox +++ b/documentation/doxygen/system.dox @@ -1,13 +1,13 @@ /** @page system System Programming -Lower level aspects of software development for Flipper Zero. +Lower-level aspects of software development for Flipper Zero. -- @subpage unit_tests - Automated testing, a crucial part of the development process -- @subpage furi_check - Hard checks for exceptional situations -- @subpage furi_hal_bus - Access the on-chip peripherals in a safe way -- @subpage furi_hal_debugging - Low level debugging features -- @subpage hardware_targets - Support for different hardware platforms -- @subpage firmware_assets - Various files required for building the firmware -- @subpage dolphin_assets - Animations for the Dolphin game +- @subpage unit_tests — Automated testing, a crucial part of the development process +- @subpage furi_check — Hard checks for exceptional situations +- @subpage furi_hal_bus — Access the on-chip peripherals in a safe way +- @subpage furi_hal_debugging — Low-level debugging features +- @subpage hardware_targets — Support for different hardware platforms +- @subpage firmware_assets — Various files required for building the firmware +- @subpage dolphin_assets — Animations for the Dolphin game */ diff --git a/documentation/fbt.md b/documentation/fbt.md index fee003abb09..59f6aa154eb 100644 --- a/documentation/fbt.md +++ b/documentation/fbt.md @@ -3,7 +3,7 @@ FBT is the entry point for firmware-related commands and utilities. It is invoked by `./fbt` in the firmware project root directory. Internally, it is a wrapper around [scons](https://scons.org/) build system. -If you don't need all features of `fbt` - like building the whole firmware - and only want to build and debug a single application, you can use [ufbt](https://pypi.org/project/ufbt/). +If you don't need all features of `fbt` — like building the whole firmware — and only want to build and debug a single app, you can use [ufbt](https://pypi.org/project/ufbt/). ## Environment @@ -40,7 +40,7 @@ To run cleanup (think of `make clean`) for specified targets, add the `-c` optio `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 (it is used for code completion support in IDEs). -`build/latest` symlink & compilation database are only updated upon *firmware build targets* - that is, when you're re-building the firmware itself. Running other tasks, like firmware flashing or building update bundles *for a different debug/release configuration or hardware target*, does not update `built/latest` dir to point to that configuration. +`build/latest` symlink & compilation database are only updated upon *firmware build targets* — that is, when you're re-building the firmware itself. Running other tasks, like firmware flashing or building update bundles *for a different debug/release configuration or hardware target*, does not update `built/latest` dir to point to that configuration. ## VSCode integration @@ -51,7 +51,7 @@ To use language servers other than the default VS Code C/C++ language server, us - 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). + - 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. @@ -62,70 +62,70 @@ To use language servers other than the default VS Code C/C++ language server, us ### High-level (what you most likely need) -- `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 over SWD interface with supported probes. Probe is detected automatically; you can override it with `SWD_TRANSPORT=...` variable. If multiple probes are attached, you can specify the serial number of the probe to use with `SWD_TRANSPORT_SERIAL=...`. -- `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. -- `devboard_flash` - Update WiFi dev board. Supports `ARGS="..."` to pass extra arguments to the update script, e.g. `ARGS="-c dev"`. -- `blackmagic` - debug firmware with Blackmagic probe (WiFi dev board). -- `openocd` - just start OpenOCD. You can pass extra arguments with `ARGS="..."`. -- `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 `SWD_TRANSPORT_SERIAL=...`. -- `lint`, `format` - run clang-format on the C source code to check and reformat it according to the `.clang-format` specs. Supports `ARGS="..."` to pass extra arguments to clang-format. -- `lint_py`, `format_py` - run [black](https://black.readthedocs.io/en/stable/index.html) on the Python source code, build system files & application manifests. Supports `ARGS="..."` to pass extra arguments to black. -- `lint_img`, `format_img` - check the image assets for errors and format them. Enforces color depth and strips metadata. -- `lint_all`, `format_all` - run all linters and formatters. -- `firmware_pvs` - generate a PVS Studio report for the firmware. Requires PVS Studio to be available on your system's `PATH`. -- `doxygen` - generate Doxygen documentation for the firmware. `doxy` target also opens web browser to view the generated documentation. -- `cli` - start a Flipper CLI session over USB. +- `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 over SWD interface with supported probes. Probe is detected automatically; you can override it with `SWD_TRANSPORT=...` variable. If multiple probes are attached, you can specify the serial number of the probe to use with `SWD_TRANSPORT_SERIAL=...`. +- `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. +- `devboard_flash` — Update WiFi dev board. Supports `ARGS="..."` to pass extra arguments to the update script, e.g. `ARGS="-c dev"`. +- `blackmagic` — debug firmware with Blackmagic probe (WiFi dev board). +- `openocd` — just start OpenOCD. You can pass extra arguments with `ARGS="..."`. +- `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 `SWD_TRANSPORT_SERIAL=...`. +- `lint`, `format` — run clang-format on the C source code to check and reformat it according to the `.clang-format` specs. Supports `ARGS="..."` to pass extra arguments to clang-format. +- `lint_py`, `format_py` — run [black](https://black.readthedocs.io/en/stable/index.html) on the Python source code, build system files & app manifests. Supports `ARGS="..."` to pass extra arguments to black. +- `lint_img`, `format_img` — check the image assets for errors and format them. Enforces color depth and strips metadata. +- `lint_all`, `format_all` — run all linters and formatters. +- `firmware_pvs` — generate a PVS Studio report for the firmware. Requires PVS Studio to be available on your system's `PATH`. +- `doxygen` — generate Doxygen documentation for the firmware. `doxy` target also opens web browser to view the generated documentation. +- `cli` — start a Flipper CLI session over USB. ### Firmware targets -- `faps` - build all external & plugin apps as [`.faps`](AppsOnSDCard.md). +- `faps` — build all external & plugin apps as [`.faps`](AppsOnSDCard.md). - `fbt` also defines per-app targets. For example, for an app with `appid=snake_game` target names are: - - `fap_snake_game`, etc. - build single app as `.fap` by its application ID. - - Check out [`--extra-ext-apps`](#command-line-parameters) for force adding extra apps to external build. - - `fap_snake_game_list`, etc - generate source + assembler listing for app's `.fap`. -- `flash`, `firmware_flash` - flash the current version to the attached device over SWD. -- `jflash` - flash the current version to the attached device with JFlash using a J-Link probe. The JFlash executable must be on your `$PATH`. -- `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. + - `fap_snake_game`, etc. — build single app as `.fap` by its app 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 over SWD. +- `jflash` — flash the current version to the attached device with JFlash using a J-Link probe. The JFlash executable must be on your `$PATH`. +- `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 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 +- `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 {#command-line-parameters} -- `--options optionfile.py` (default value `fbt_options.py`) - load a file with multiple configuration values -- `--extra-int-apps=app1,app2,appN` - force listed apps to be built as internal with the `firmware` target -- `--extra-ext-apps=app1,app2,appN` - force listed apps to be built as external with the `firmware_extapps` target -- `--extra-define=A --extra-define=B=C ` - extra global defines that will be passed to the C/C++ compiler, can be specified multiple times -- `--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. +- `--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 +- `--extra-define=A --extra-define=B=C ` — extra global defines that will be passed to the C/C++ compiler, can be specified multiple times +- `--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 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 also create a file called `fbt_options_local.py` that will be evaluated when loading default options file, enabling persisent overriding of default options without modifying default configuration. +You can also create a file called `fbt_options_local.py` that will be evaluated when loading default options file, enabling persistent overriding of default options without modifying default configuration. You can find out available options with `./fbt -h`. ### Firmware application set -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. +You can create customized firmware builds by modifying the list of apps to be included in the build. App presets are configured with the `FIRMWARE_APPS` option, which is a `map(configuration_name:str → application_list:tuple(str))`. To specify an app 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. diff --git a/documentation/file_formats/NfcFileFormats.md b/documentation/file_formats/NfcFileFormats.md index 5b08c3471fd..da0b0a19d6e 100644 --- a/documentation/file_formats/NfcFileFormats.md +++ b/documentation/file_formats/NfcFileFormats.md @@ -38,7 +38,7 @@ Version differences: ### Description -This file format is used to store the UID, SAK and ATQA of a ISO14443-3A device. +This file format is used to store the UID, SAK and ATQA of an ISO14443-3A device. UID must be either 4 or 7 bytes long. ATQA is 2 bytes long. SAK is 1 byte long. Version differences: diff --git a/documentation/file_formats/TarHeatshrinkFormat.md b/documentation/file_formats/TarHeatshrinkFormat.md index 86c27a698eb..79b75416b9b 100644 --- a/documentation/file_formats/TarHeatshrinkFormat.md +++ b/documentation/file_formats/TarHeatshrinkFormat.md @@ -1,6 +1,6 @@ -# Heatshrink-compressed Tarball Format +# Heatshrink-compressed Tarball Format {#heatshrink_file_format} -Flipper supports the use of Heatshrink compression library for .tar archives. This allows for smaller file sizes and faster OTA updates. +Flipper supports the use of Heatshrink compression library for `.tar` archives. This allows for smaller file sizes and faster OTA updates. Heatshrink specification does not define a container format for storing compression parameters. This document describes the format used by Flipper to store Heatshrink-compressed data streams. diff --git a/documentation/js/js_badusb.md b/documentation/js/js_badusb.md index 78c49104ca5..b21126dfcbd 100644 --- a/documentation/js/js_badusb.md +++ b/documentation/js/js_badusb.md @@ -67,7 +67,7 @@ badusb.hold("CTRL", "v"); // Press and hold CTRL + "v" combo ``` ## release -Release a previously hold key. +Release a previously held key. ### Parameters Same as `press` diff --git a/documentation/js/js_data_types.md b/documentation/js/js_data_types.md index de1c896dce3..bd3bb1f426f 100644 --- a/documentation/js/js_data_types.md +++ b/documentation/js/js_data_types.md @@ -1,13 +1,13 @@ # Data types {#js_data_types} Here is a list of common data types used by mJS. -- string - sequence of single byte characters, no UTF8 support +- string — sequence of single byte characters, no UTF8 support - number - boolean -- foreign - C function or data pointer +- foreign — C function or data pointer - undefined - null -- object - a data structure with named fields -- array - special type of object, all items have indexes and equal types -- ArrayBuffer - raw data buffer -- DataView - provides interface for accessing ArrayBuffer contents +- object — a data structure with named fields +- array — special type of object, all items have indexes and equal types +- ArrayBuffer — raw data buffer +- DataView — provides interface for accessing ArrayBuffer contents diff --git a/documentation/js/js_math.md b/documentation/js/js_math.md index 296f01c62db..12dae8fb377 100644 --- a/documentation/js/js_math.md +++ b/documentation/js/js_math.md @@ -290,7 +290,7 @@ math.pow(2, 10); // 1024 ``` ## random -Return a floating-point, pseudo-random number that's greater than or equal to 0 and less than 1, with approximately uniform distribution over that range - which you can then scale to your desired range. +Return a floating-point, pseudo-random number that's greater than or equal to 0 and less than 1, with approximately uniform distribution over that range — which you can then scale to your desired range. ### Returns A floating-point, pseudo-random number between 0 (inclusive) and 1 (exclusive).