diff --git a/wiki/Basic-features.md b/wiki/Basic-features.md new file mode 100644 index 000000000..c6b0a9640 --- /dev/null +++ b/wiki/Basic-features.md @@ -0,0 +1,7 @@ +### Pass-code lock + +Flipper will store your secrets like U2F token and house keys. What if Flipper gets lost? + +Well, no problem! For this case, we made a locking feature. You can lock Flipper and unlock it with the special pass-combo, like in good old fighting games (for example, →↑↑←↓↑↓). Users can set a pass-combo of any length, and all functions will be blocked until the combo is entered, including firmware flashing. + +![](https://ksr-ugc.imgix.net/assets/030/153/925/13404091a9c1bb3390a67afe279a0051_original.gif?ixlib=rb-2.1.0&w=700&fit=max&v=1597158235&auto=format&gif-q=50&q=92&s=06a640ecaa809487b004c1bead0fd9cc) \ No newline at end of file diff --git a/wiki/Contributing.md b/wiki/Contributing.md new file mode 100644 index 000000000..3570a992e --- /dev/null +++ b/wiki/Contributing.md @@ -0,0 +1,76 @@ +([see issue about this page](https://github.com/Flipper-Zero/flipperzero-firmware-community/labels/Area%3AContribution-guide)) + +# Getting Started + +If you are just beginning in Flipper, **Read the [wiki](https://github.com/Flipper-Zero/flipperzero-firmware-community/wiki)**. It describes general things like contribution, building and testing, and tell about main features. Flipper consists of two main parts: + +* Core: OS, HAL, FS, bootloader, FURI +* Applications: features like RFID or Tamagotchi, and also background tasks like button debouncing and control the backlight. + +## General Tips and principles + +* **Ask around for help!** If you have any questions, feel free to create an [`need help` issue](https://github.com/Flipper-Zero/flipperzero-firmware-community/issues/new?assignees=&labels=need+help&template=need-help.md&title=) or send an email to devel@flipperdevices.com. The earlier you check your feature design with other people, the less likely it is that it is denied during the review process. +* **Verify your concept early!** If you work on your own until the code looks good enough to show publicly, you might miss some design flaws others might have spotted earlier. +* **Keep it simple!** Try to use what is already there and don't change existing APIs if not absolutely necessary. +* **State your intentions** Create issue before you start your work. It will prevent a very frustrating situation where several people are doing the same job the same time. +* **Make tests `(incomplete)`** +* **Make docs** you can do very cool things but other people cannot use if it is not described in the documentation +* **We are open to changes.** You can suggest changes to any part of the code, wiki, guidelines, workflow, automation, etc. by creating issue or PR if you understand how it can be done better. + +## Status of wiki sections + +* Some sections mark as `incomplete`. This means that there is not even a description of how the feature can be implemented. You can start [discussion](https://github.com/Flipper-Zero/flipperzero-firmware-community/issues/new?assignees=&labels=discussion&template=discuss-issue.md&title=) thread or directly begin to write wiki page (see [Contributing](#contributing)). +* Some sections mark as `not implemented`. It have description but there is nothing that would make this description into reality. +* Some sections mark as `not documented`. There is some implementation and you can add some documentation here. +* If section of wiki has no mark, this is actual documentation for part of Flipper. + +## Wiki storage `(not implemented)` + +All wiki files storage in main repository in `wiki` folder. You can change wiki by creating PR with `documentation` label. After merge to master, wiki contents copying to GitHub `Wiki` section. + +# Maintainers + +Every section/page of wiki and related part of code has its own maintainers. Maintainers list and related code folders is placed at the bottom of page or section. + +If contributors cannot reach consensus during a discussion or code review, you can add a [needs moderating](https://github.com/Flipper-Zero/flipperzero-firmware-community/labels/needs%20moderating) label. Maintainers has the final say in the discussion. + +If maintainers cannot reach consensus, Flipper devices CTO ([`@glitchcore`](https://github.com/glitchcore)) has the final say in the discussion. + +# Issues + +Please notice that we use a bunch of tags to label the issues. + +All issues are, if possible, tied to sections in the wiki with `Area:` labels. + +Full list of labels you can find at [labels list page](https://github.com/Flipper-Zero/flipperzero-firmware-community/labels). + +# Contributing + +If you want to add some features or suggest some changes, do following steps: + +1. Choose section which you want to improve +2. Check existing issues and PR by `Area` tag. Maybe somebody create discussion about your improvement or already doing some work. +3. Choose your way: + * If you have some idea about new feature, you can create **[feature request](https://github.com/Flipper-Zero/flipperzero-firmware-community/issues/new?assignees=&labels=feature+request&template=feature_request.md&title=)** + * If you find some bug, you can create **[bug report](https://github.com/Flipper-Zero/flipperzero-firmware-community/issues/new?assignees=&labels=bug&template=bug_report.md&title=)** + * You can ask for help if you are not sure how to implement your idea or discuss implementation details by creating **[discuss issue](https://github.com/Flipper-Zero/flipperzero-firmware-community/issues/new?assignees=&labels=discussion&template=discuss-issue.md&title=)**. +4. Otherwise, make you improvement: + * Clone actual repository. + * Create a branch + * Make commits + * Push your branch and create a [pull request](#pull-requests) + * Wait for maintainers feedback. + * Your code is merged in master branch +5. If you can do only part of work, create PR with `WIP` label. Describe what you have already done and what remains to be done and other people can help you. + +## Pull requests + +1. Don't forget reference issues or other PR +2. Add `Area:` label to PR +3. Remember that smaller PRs tend to be merged faster, so keep your changes as concise as possible. They should be confined to a single explainable change, and be runnable on their own. So don't hesitate to split your PRs into smaller ones when possible. +4. If you only create description at wiki but no implementation existing, don't forget to add `not implemented` mark. +5. We strongly recommend documenting your code and creating wiki descriptions at the same time as improvement the code. If you have no energy left for documentation, at least mark the appropriate section of the wiki as `not documented`, or you can create `WIP` PR and wait for help. + +### Large and static files storage (incomplete) + +_Maintainers of this page: [`@glitchcore`](https://github.com/glitchcore)_ \ No newline at end of file diff --git a/wiki/Home.md b/wiki/Home.md new file mode 100644 index 000000000..3a742c77f --- /dev/null +++ b/wiki/Home.md @@ -0,0 +1,73 @@ +Welcome to the flipperzero-firmware wiki! + +Flipper zero is open source multi-tool device for researching and pentesting radio protocols, access control systems, hardware, and more. + +# Building + +See [Building instructions](Firmware#building) + +# How to contribute + +To contribute to code or to wiki make the following steps: + +1. Read this wiki +2. Read [contribution guide](Contributing) +3. Ensure you read and sign [Flipper CLA](https://cla-assistant.io/glitchcore/flipper-cla-host) +4. Read Flipper [Roadmap](Flipper-roadmap) + +# UI + +Common UI feature (menu, screens, features) at [UI page](UI) + +# Features + +* [Basic Features](Basic-features) +* [Sub-1 GHz radio](Sub-1-GHz-radio) (Transceiver Based on CC1101 chip for 315/433/868 MHz) +* [125 kHz RFID](125-kHz-RFID) +* [Infrared](Infrared) +* [iButton contact keys](iButton-contact-keys) +* [USB](USB) +* [Bluetooth](Bluetooth) +* [GPIO/HW Modules](GPIO) +* [NFC](NFC) +* [U2F](U2F) +* [Tamagotchi](Tamagotchi) +* [USB](USB) +* [Plugins](Plugins) + +# PlatformIO & Arduino +* Easy IDE deploying +* Cross platform HID device without drivers +* Ready to use library for LCD, Buttons, CC1101, GPIO, Infrared, 125khz, Bluetooth? NFC? + +# Hardware + +[Hardware specification](Hardware-specification) + +### Releases + +All PCB releases named according to the following rules: + +* `F` mean fw target. Different F-versions has different firmware. +* `B` mean body. Different B-versions has mechanical incompatibility. If B=0, PCB is not intended for installation in a case. +* `C` mean interConnections. If С=0, device contain single board and no interconnections. Otherwise, different C-versions is incompatible to each other. +* Number afer point mean sequential numbering of release. + +List of releases: + +* [Version 0 (F1B1C0)](Hardware-version-F1B1C0.0) +* [Version 1 (F2B0C1)](Hardware-version-F2B0C1.1) + +### Hardware components + +* LCD display [buydisplay.com](https://www.buydisplay.com/1-4-inch-graphic-128x64-lcd-module-serial-spi-st7565-black-on-white) + +# Firmware + +[Firmware description page](Firmware) + +# Links + +* Project website: [flipperzero.one](https://flipperzero.one) +* Kickstarter page: [kickstarter.com](https://www.kickstarter.com/projects/flipper-devices/flipper-zero-tamagochi-for-hackers) +* Forum: [forum.flipperzero.one](https://forum.flipperzero.one/) \ No newline at end of file diff --git a/wiki/Roadmap.md b/wiki/Roadmap.md new file mode 100644 index 000000000..8b32ed9f9 --- /dev/null +++ b/wiki/Roadmap.md @@ -0,0 +1,38 @@ +Hello and welcome + +We make some PoC firmware: check hardware feature and UI example. + +Now we start PO-NASTOYASCHEMU! + +Phase 1: warm-up + +Create some community, contribution guide, IDE integration, build and test/CI system. +Describe all feature and close to its implementation. +Choose OS/HAL, maybe Rust. +Implement basic API. +Implement emulator. (target:Emul) +Implement remote debug testbench (target:F1) +Describe bootloader and linking system. +Begin developing applications. + +Up to 10 sep. + +Phase 2: hardware gen 1 + +Send contributor's kit to contributors. +Implement bootloader, core, tests. +PlatformIO/Arduino integration. +Debug developing applications on real hw (target:F2) + +Up to 30 sep. + +Phase 3: hardware gen 2 + +Send contributor's kit with BLE/other HW fixes. + +Implement bluetooth +Debug core on target:F3. +Developing applications. +Improve core. + +Up to feb 2021 diff --git a/wiki/UI.md b/wiki/UI.md new file mode 100644 index 000000000..f9f806732 --- /dev/null +++ b/wiki/UI.md @@ -0,0 +1,21 @@ +## Main menu + + + +* [443/866Mhz Transceiver](Sub-1-GHz-radio) +* [Proximity tag 125khz](125-kHz-RFID) +* [Bad USB](USB) +* [Infrared](Infrared) +* [iButton (1-Wire)](iButton-contact-keys) +* [Plugins](Plugins) +* Settings +* [Dolphin](Tamagotchi) + +## Settings menu + +* Display +* Power + +## Additional features + +* PIN code for unlock (влево-вверх-вправо-вниз-вниз) \ No newline at end of file diff --git a/wiki/features/125-kHz-RFID.md b/wiki/features/125-kHz-RFID.md new file mode 100644 index 000000000..925db2d00 --- /dev/null +++ b/wiki/features/125-kHz-RFID.md @@ -0,0 +1,59 @@ +![Flipper Zero RFID](https://habrastorage.org/webt/jd/fb/yb/jdfbybzgw6qvg5kjeuvfg8w0iou.png) + +Low-frequency proximity cards are widely used in access control systems around the world. It's pretty dumb, keeps only a short few-byte ID, and has no authentication mechanism, allowing it to be easily read, cloned, and emulated by anyone. A 125 kHz antenna is located on the bottom of Flipper's body. + +## Card types supported + +### Mandatory +* EM400x, EM410x, EM420x +* HID Prox (Proxcard, ISOProx, ProxKey). Not project Keysy told: _Emulation not supported on multiClass readers, can still clone to rewritable_ +* HID Indala (Motorola Indala) +* Write to T55x7 compatible keycard/keyfob + + +### Optional +* Noralsy (KCP3000) +* Farpointe Pyramid +* Keri (KC-10X, MT-10X, PKT-10X) +* Kantech ioProx +* DoorKing (DKProx) [Not DKProx Long Range] +* AWID (Low frequency only – CS-AWID, GR-AWID, KT-AWID, PW-AWID) + Keysy note: (Emulation not supported, can still clone to rewritable) +* Radio Key (SecuraKey RKKT-01, RKKT-02) +* Viking +* Visa2000 +* Schlage IBF iButton (RFID portion only) + +### Exotic +* Pet tags + +## Features + +### Reading +* Read specific card type, save ID +* card type detection (testing all protocols one by one, and read ID if found) + +### Emulation +* Emulate saved cards +* Enter card ID and card type manually to saved ID library +_You can also emulate the card by entering its ID manually, so you can easily send it to your friend in a text format. Thus, Flipper owners can exchange card dumps with each other remotely without ever touching a physical card._ + +### Write card +* Write to T55x7 compatible keycard/keyfob + + +## Links + +* https://scanlime.org/2008/09/using-an-avr-as-an-rfid-tag/ +* [ESP8266 em4100 emulator](https://github.com/Crypter/ESP-RFID) +* https://www.kickstarter.com/projects/1708444109/rfidler-a-software-defined-rfid-reader-writer-emul +* https://github.com/AlexMalov/EasyKeyDublicatorRFID +* https://shop.hak5.org/products/keysy + +# UI + +## Main menu + +* Read +* Saved Keys +* Enter manually \ No newline at end of file diff --git a/wiki/features/Bluetooth.md b/wiki/features/Bluetooth.md new file mode 100644 index 000000000..1cb853c66 --- /dev/null +++ b/wiki/features/Bluetooth.md @@ -0,0 +1,6 @@ +Bluetooth module will allow you to interact with Flipper using your smartphone, as well as transfer interfaces like UART and SPI to your computer wirelessly. + + +## Bluetooth Serial adapter + +User can connect Flipper Zero to UART port via GPIO and get access via Bluetooth \ No newline at end of file diff --git a/wiki/features/GPIO.md b/wiki/features/GPIO.md new file mode 100644 index 000000000..71e3be13e --- /dev/null +++ b/wiki/features/GPIO.md @@ -0,0 +1,3 @@ +Flipper Zero can be used as a versatile tool for hardware hacking. Its 12 built-in GPIO pins are 5V tolerant and allow you to connect it to any piece of hardware while running your own code, controlling it with buttons and printing debug messages to the LCD display. + +You can use it as a handy firmware flashing, debugging, and fuzzing device, as well as USB to UART/SPI/I2C/etc adapter connected to the PC. \ No newline at end of file diff --git a/wiki/features/Infrared.md b/wiki/features/Infrared.md new file mode 100644 index 000000000..3f2d92703 --- /dev/null +++ b/wiki/features/Infrared.md @@ -0,0 +1,19 @@ +The infrared transmitter can send any signal to control electronics such as TV, air conditioners, stereo systems, and others. + +## Signal library + +Flipper contains a built-in library of common remote commands like switching on/off, changing volume or adjusting temperature, and so on. This library is constantly updated by Flipper community users that upload new signals to Flipper's IR remote database. + +## Infrared learning feature + +At the same time, the IR receiver can catch signals and save them to the memory, so you can store any of your personal remotes and transmit it later, as well as upload it to the public database to share with other Flipper users. + +Flipper's infrared eye can automatically detect baud rate, frequency, and modulation of the IR signals it captures without any configuration. That allows you to easily capture and store signals from all your remotes and other IR appliances. + +# UI + +## Main menu + +* Library +* Read +* Saved signals \ No newline at end of file diff --git a/wiki/features/NFC.md b/wiki/features/NFC.md new file mode 100644 index 000000000..74d31933b --- /dev/null +++ b/wiki/features/NFC.md @@ -0,0 +1,22 @@ +The NFC standard (ISO-14443) operates at 13.56MHz. We are going to use the ST25R3916 chip, the same chip as used in the HydraNFC project. + +Supported cards: + +* ISO-14443 tag (mifare?) reading & writing & emulation +* Emulation — Mifare Classic & Ultralight + + +## Reader mode + + +## Write mode + + +## Emulate mode + + +# UI + +### NFC +* Reader +* Emaulte \ No newline at end of file diff --git a/wiki/features/Plugins.md b/wiki/features/Plugins.md new file mode 100644 index 000000000..23125cc24 --- /dev/null +++ b/wiki/features/Plugins.md @@ -0,0 +1,6 @@ +Users can add their own applications. Third party apps placed in `Plugins` menu. + +## Plugins list + +* USB -> UART +* Servo \ No newline at end of file diff --git a/wiki/features/Sub-1-GHz-radio.md b/wiki/features/Sub-1-GHz-radio.md new file mode 100644 index 000000000..d69d58dd3 --- /dev/null +++ b/wiki/features/Sub-1-GHz-radio.md @@ -0,0 +1,49 @@ +To communicate with the real world systems, Flipper Zero has a built-in radio module based on TI CC1101 chip. It supports both transmitting and receiving digital signals within the 300-928 MHz frequency range. This is the operating range for a wide class of devices and access control systems such as garage doors remotes, boom barriers, IoT sensors, and remote keyless systems. + +Out of the box, Flipper Zero can emulate remotes for popular garage doors and barriers. You can keep hundreds of remotes in Flipper's memory as well as create a blank remote for the new wireless gate. Just select the right brand of the system in the Flipper menu, register a new key in your garage/barrier receiver, and give it a unique name for easy navigation between your remotes. + +CC1101 is well known universal transceiver designed for low-power wireless applications. And with a ready-to-use open-source library, developers can interact with the radio subsystem without limitations. You can write any wireless application, like custom protocol or decoder, as well as use it for connecting with IoT devices and access systems. + + +## Frequency Scaner (Spectrum analyzer) + +User should be able to detect which frequency used in specific device. For example detect if unknown remote transmit on 433MHz or 868MHz + +![frequency scan example](https://github.com/Flipper-Zero/wiki/raw/master/images/rf_scan.png) + +## Signal Analyzer + +Detect frequency and modulation: + +* ASK +* FSK + +## Protocol Decoder + +* Works on 315/433/868 MHz + +Flipper Zero has an integrated decoder for popular remote control algorithms such as Keeloq and others, so you can analyze an unknown radio system to figure out the protocol under the hood. + +## Signal recorder + +Furthermore, Flipper can record the samples of radio signals to analyze it later with more sophisticated tools on the computer, as well as replay the saved samples. Many remotes and IoT devices such as doorbells, sensors, and radio sockets don't use any encryption at all — in this case, Flipper can replay the signal, even if the protocol wasn't recognized. + + +### Protocol Decoder demo + +https://www.youtube.com/watch?v=AeCGLFKsxCU +* Detect protocol and parse it +* Analyze if it's secure on not + + +## Common Dummy Remote + +User can use flipper as normal dummy remote for their own reciever like garage door. +For this flipper should have library of popular remotes brands. + +# UI + +## Main menu + +* Sniffer +* Saved \ No newline at end of file diff --git a/wiki/features/Tamagotchi.md b/wiki/features/Tamagotchi.md new file mode 100644 index 000000000..01d2bb8c9 --- /dev/null +++ b/wiki/features/Tamagotchi.md @@ -0,0 +1,3 @@ +* Dolphin Levels — каждое активное хакерское действие увеличивает уровень дельфина +* Dolphin emotional status — если долго не играть, то дельфин начинает вести себя тупо, становится неактивным, заванивается, протухает +* Dolphin games \ No newline at end of file diff --git a/wiki/features/U2F.md b/wiki/features/U2F.md new file mode 100644 index 000000000..781da6168 --- /dev/null +++ b/wiki/features/U2F.md @@ -0,0 +1,9 @@ +Flipper Zero can act as a fully functional U2F key, that works with any U2F-enabled services such as Google, Twitter, Facebook, Dropbox, LastPass, Amazon AWS, and many others. + +Universal 2nd Factor (U2F) protocol is an open standard for hardware security tokens used for secure authentication. Developed by Google, Yubico, and NXP, U2F acts as a universal key that is designed to add another layer to the traditional login+password authentication method. + +Even if your password gets compromised, an attacker will not be able to log in to your account. This method is much stronger than the usual SMS 2nd-factor method, as it doesn’t involve any third-parties like a cell phone operator. + +### Links + +https://github.com/solokeys/solo \ No newline at end of file diff --git a/wiki/features/USB.md b/wiki/features/USB.md new file mode 100644 index 000000000..e5adcd3d5 --- /dev/null +++ b/wiki/features/USB.md @@ -0,0 +1,19 @@ +As we all know, computers completely trust connected input devices like mouse and keyboard. Flipper Zero can emulate a USB slave device, allowing it to be recognized by the computer as a regular input device, such as HID keyboard or Ethernet adapter, just as USB Rubber Ducky. You can write your own keyboard payloads to type any key sequence, as well as fuzzing USB stack on a target device. + +## Flashing firwmare (HID mode) +Firmware mode activating only when chosen from menu. + +## Bad USB mode +Allow user to run scripts from menu. User should choose script before connecting to victim PC. + +## USB Serial mode +GPIO can act as UART/I2C/SPI so user can use Flipper as PC serial adapter. + +# UI + + +### Firmware update + +### Bad USB +* Payloads +* Settings \ No newline at end of file diff --git a/wiki/features/iButton-contact-keys.md b/wiki/features/iButton-contact-keys.md new file mode 100644 index 000000000..fba22d52b --- /dev/null +++ b/wiki/features/iButton-contact-keys.md @@ -0,0 +1,22 @@ +Flipper Zero has a built-in 1-Wire pad to read iButton (DS1990A) keys, also known as TouchMemory or Dallas keys. This technology is quite old but still widely used around the world. It's based on 1-Wire protocol and doesn't have any authentication, so Flipper can easily read these keys, save IDs into the memory, write IDs to blank keys, and emulate the key itself. + +* **Reading & Writing & Emulating** +* **Protocol detection**: юзер может определить тип ключа поднося ключ к флипперу и тип считывателя поднося флиппер к домофону (цифрал, даллас и т.д.) + + + +## Reading +`iButton(1-Wire) -> Reading` + +Flipper will wait for iButton tag. While waiting red LED is blinking. +Lean tag on iButton reader in the back side of Flipper Zero: + + + +# UI + +## Main menu + +* Read +* Saved Keys +* Enter manually \ No newline at end of file diff --git a/wiki/fw/FURI-records-list.md b/wiki/fw/FURI-records-list.md new file mode 100644 index 000000000..c6a489b78 --- /dev/null +++ b/wiki/fw/FURI-records-list.md @@ -0,0 +1,59 @@ +List of [FURI](FURI) records for exchange data between applications. + +# Interrupts + +* `/irq/buttons` — raw button press/release events. + +|Name|Type|Size| +|---|---|---| +|Button|0 — Up
1 — Down
2 — Right
3 — Left
4 — Ok
5 — Back|1| +|State|1 — pressed
0 — released|1| + +* `/irq/charge` — charge state event + +# UI + +|Name|Type|Size| +|---|---|---| +|State|1 — charge start
0 — charge stop|1| + +* `/ui/fb` — pointer to current framebuffer + +|Name|Type|Size| +|---|---|---| +|Framebuffer pointer|`uint8_t[DISPLAY_WIDTH][DISPAY_HEIGHT]`|4| + +* `/ui/leds` — user led state + +Led state is overrided by charge state (red when charging, green when charged). + +|Name|Type|Size| +|---|---|---| +|Red|pwm value (0..255)|1| +|Green|pwm value (0..255)|1| +|Blue|pwm value (0..255)|1| +|Enable|1 — user led enabled
0 — user led disabled (for manual led control)|1| + +* `/ui/buttons_event` — button press/release events after debounce. + +|Name|Type|Size| +|---|---|---| +|Button|0 — Up
1 — Down
2 — Right
3 — Left
4 — Ok
5 — Back|1| +|State|1 — pressed
0 — released|1| + +* `/ui/buttons_state` — current button state after debounce. + +|Name|Type|Size| +|---|---|---| +|Up|1 — pressed
0 — released|1| +|Down|1 — pressed
0 — released|1| +|Right|1 — pressed
0 — released|1| +|Left|1 — pressed
0 — released|1| +|Ok|1 — pressed
0 — released|1| +|Back|1 — pressed
0 — released|1| + +* `/ui/fullscreen` — fullscreen mode state + +|Name|Type|Size| +|---|---|---| +|State|1 — fullscreen
0 — no fullscreen|1| \ No newline at end of file diff --git a/wiki/fw/FURI.md b/wiki/fw/FURI.md new file mode 100644 index 000000000..24c31df56 --- /dev/null +++ b/wiki/fw/FURI.md @@ -0,0 +1,54 @@ +Flipper Universal Registry Implementation or FURI is important part of Flipper firmware. It is used to: + +* application control (start, exit, switch between active) +* data exchange between application (create/open channel, subscribe and push messages or read/write values) +* non-volatile data storage for application (create/open value and read/write) + +# Application registry and control (FURIAC) + +### Start and change application wrokflow + +* `FuriApp furiac_start(void(app*)(void*), char* name, void* param)` simply starts application. It call `app` entrypoint with `param` passed as argument. Useful for daemon applications and pop-up. +* `FuriApp furiac_switch(void(app*)(void*), char* name, void* param)` swtich to other application. FURI **stop current app**, call `app` entrypoint with `param` passed as argument and save current application entrypoint to `prev` field in current application registry. Useful for UI or "active" application. + +### Exit application + +* `furiac_exit(void* param)` stop current application (stop thread and clear application's stack), start application from `prev` entry in current application registry, cleanup current application registry. +* `furiac_kill(FuriApp app)` stop specified `app` without returning to `prev` application. + +# Data exchange + +* `FuriRecord furi_create(char* name)` creates named FURI record. Returns NULL if registry have not enough memory for creating. +* `FuriRecord furi_open(char* name, bool solo, bool no_mute)` opens existing FURI record by name. Returns NULL if record does not exist. If `solo` is true **another applications handlers set into "muted" state**. When appication has exited or record has closed, all handlers is unmuted. It may be useful for concurrently acces to resources like framebuffer or beeper. If `no_mute` is true, another applications cannot mute this handler. +* `bool furi_close(FuriRecord record)` close handler and unmute anothers. +* `bool furi_read(FuriRecord record, void* data, size_t size)` read message from record. Returns true if success, false otherwise. +* `bool furi_write(FuriRecord record, const void* data, size_t size)` write message to record. Returns true if success, false otherwise (handler gone or muted). +* `bool furi_take(FuriRecord record, void* data, size_t size)` works as `furi_read` but lock global mutex. It can be useful if records contain pointer to buffer which you want to change. You must call `furi_give` after operation on data and you cannot block executing between `take` and `give` calls +* `bool furi_give(FuriRecord record, const void* data, size_t size)` works as `furi_wrte` but unlock global mutex. +* `bool furi_global_take()` lock global mutex (as `furi_take` but without read) +* `boold furi_global_give()` unlock global mutex ((as `furi_give` but without write)) +* `bool furi_unmute(FuriRecord record)` unmutes muted record. +* `bool furi_mute(FuriRecord record)` mutes unmuted record. +* `bool furi_subscribe(FuriRecord record, void(cb*)(const void* data, size_t size))` set record change callback. +* `bool furi_state_subscribe(FuriRecord record, void(cb*)(bool muted))` set record state change callback (mute/unmute). For example, you can unmute itself after some application open same record, or redraw your application UI when popup application ends. + +# Usage example +_Diagram below describes furi states_ + +![FURI states](https://github.com/Flipper-Zero/wiki/raw/master/images/furi_states.png) + +* After start, init code run some applications: in this example there is status bar, a background task and Home screen +* Status bar open access to framebuffer by opening "/ui/fb" FURI record +* "Home screen" call "Menu" application by `furiac_switch`. "Home screen" application stops and then "Menu" application starts. +* "Menu" application call "Your cool app" the same way. It also get access to framebuffer by open "/ui/fb" FURI record +* If "Your cool app" needs some backend app, it call this by `furiac_start` and then kill by `furiac_kill` +* If background task needs to show popup message (for example "Low battery") it can call new app or simply open "/ui/fb" record. +* When "/ui/fb" record is opened by popup message, FURI mute framebuffer handle in "Your cool app". This prevent to overwrite popup message by application drawing. +* "Status bar" framebuffer handle also is muted, but it call `furi_unmute` and unmute itself. +* After popup message is closed by `furiac_exit` or closing "/ui/fb", FURI unmute previous muted "Your cool app" framebuffer handle. + +_Status bar also get mute and unmute itself every time when Home screen, Menu or "Your cool app" open framebuffer but diagramm not show it_ + +# Data storage + +* `furi_create_var(char* name)` create static-like value handler. You can use all furi_ calls for \ No newline at end of file diff --git a/wiki/fw/Firmware.md b/wiki/fw/Firmware.md new file mode 100644 index 000000000..361744ee8 --- /dev/null +++ b/wiki/fw/Firmware.md @@ -0,0 +1,117 @@ +_Overview of Flipper firmware architecture:_ + +![FW arch](https://github.com/Flipper-Zero/wiki/raw/master/images/flipper_fw_arch.png) + +# HAL + +We use STM32 HAL/LL. Description available here: [dm00105879.pdf](https://github.com/Flipper-Zero/wiki/raw/master/dm00105879-description-of-stm32f4-hal-and-ll-drivers-stmicroelectronics.pdf) + +## Flipper HAL + +Some flipper-specific implementation of gpio/HAL: + +* Init gpio pin: `app_gpio_init` +* Fast write gpio (inline): `app_gpio_write` +* Fast read gpio (inline): `app_gpio_read` +* Microsecond delay `delay_us` +* Set PWM on timer's pin: `pwm_set` + +Files location: `/app/app_hal.[ch]` + +# OS + +We use FreeRTOS 10.0.1 for sheduling. Documentation available on [freertos.org](https://www.freertos.org/a00106.html). + +Files location for L476 version: `/target_prod/Middlewares/Third_Party/FreeRTOS` + +**[Timers map](Timers)** + +# Platform code + +CMSIS, Freertos and HAL files are generated by CubeMX. +You can find platform code for L476 version in `target_prod` folder: + +* `Drivers/STM32L4xx_HAL_Driver` – hardware abstraction layer +* `Drivers/CMSIS` — ARM specific code +* `Inc` `Src` — CubeMX generated headers & code +* `Middlewares/Third_Party/FreeRTOS/Source` — freeRTOS +* `deploy.sh` — flash firmware to device +* `STM32L476RGTx_FLASH.ld` — linker script +* `startup_stm32l476xx.s` — board startup/initialization assembler code +* `flipperzero_l476.ioc` — CubeMX project file + +You can regenerate platform code: +1. Download CubeMX from [st.com](https://www.st.com/en/development-tools/stm32cubemx.html) +2. Open `*.ioc` file +3. Click `generate code` +4. After regenerating, look at git status, regenerating may broke some files. + +## Arduino compatibility + +There are some arduino-style defines (digitalWrite, delay, etc.). Include `Arduino.h` from `/app/Arduino.h` + +## Debug print + +You can use `pintf` to write any message to debug UART. UART specify in `Makefile` as `-DDEBUG_UART=<>`. + +Implementation of write method located at `/app/write.c` + +# Flipper Universal Registry Implementation (FURI) + +FURI is used to: + +* application control (start, exit, switch between active) +* data exchange between application (create/open channel, subscribe and push messages or read/write values) +* non-volatile data storage for application (create/open value and read/write) + +Read more at [FURI page](FURI) + +# FS + +File system is used to volaile storage some files (config, application data, etc.). There are some folders mounted to different volumes: + +* `/usr` for store static data like assets, menu items. Build system add files to usr while building. It can be useful for exchange some static data between application. For example, your app can add link to itself to Plugins menu items file, user will see your app and can call it from this menu. +* Specially `/usr/etc-default` folder contains default configs for apps. Bootloader has `factory default` options to reset applications config. Also when new app is bootstapping, system copy files from default config folder to `/etc`. +* `/etc` for store configs of application. This volume not overwrite during flashing. +* `/var` for store some application data (saved keys, application database, logs). This volume also not overwrite during flashing. +* `/media/*` mounted if SD card is inserted. + +# Flipper applications + +Each flipper functionality except OS/HAL/FURI doing by Flipper application. Some application are called at startup, the rest are called by the user (for example, from menu). + +**[List of Flipper applications](Flipper-applications)** + +For exchange data between application each app expose own record in FURI. You can subscribe on/read record to get data from application and write to record to send data to application. + +**[List of FURI records](FURI-records-list)** + +# Flipper libraries + +Unlike applications that run after startup, libraries are a collection of constants, types, or functions that the user can call from within the application. + +**[List of Flipper libraries](Flipper-libraries)** + +# Bootloader + +After start, bootloader run first. It can: + +1. Runs main firmware +2. Reflashes firmware from temporary area after updating from usb/bluetooth +3. Restores factory default firmware for protected flash area +4. Restores application settings to default by clearing `/etc` volume + +# Building + +## Build in docker container (main way) + +1. Install [docker compose](https://docs.docker.com/compose/install/) +2. After startup you should run `docker-compose up -d` to run the container. +3. Then you can run `docker-compose exec dev make` to build application. + +If Dockerfile is changed you should run `docker-compose down` and `docker-compose build` for rebuild the image. + +## Build in IDE + +* Arduino IDE (in progress) +* PlatformIO (in progress) \ No newline at end of file diff --git a/wiki/fw/Flipper-applications.md b/wiki/fw/Flipper-applications.md new file mode 100644 index 000000000..e69de29bb diff --git a/wiki/fw/Flipper-libraries.md b/wiki/fw/Flipper-libraries.md new file mode 100644 index 000000000..e69de29bb diff --git a/wiki/fw/Timers.md b/wiki/fw/Timers.md new file mode 100644 index 000000000..cf01e4d08 --- /dev/null +++ b/wiki/fw/Timers.md @@ -0,0 +1,61 @@ +## Tim1 + +~1 kHz, PWM + +* Ch1 -- red led +* Ch2 -- green led +* Ch3 -- blue led + +## Tim2 + +46/48 kHz, interrupt for IR. Ch4 -- IR TX + +## Tim4 + +~1 kHz, PWM + +* Ch1 -- backlight + +## Tim5 + +Variable freq. PWM. Ch4 -- speaker. + +## Tim8 + +* Ch2 -- iButton emulate + +## Tim15 + +125 kHz. Square generator and interrupt/RFID pull. + +* Ch1 -- RFID OUT (square generator) +* Ch2 -- RFID Pull + +# Devices + +## Speaker +Tim5 ch4 + +## Blue led +Tim1, Tim3, Tim8 + +## Red led +Tim1 + +## Green led +Tim15, Tim1, Tim8 + +## Backlight +Tim16, Tim4 + +## IR TX +Tim2 ch4 + +## RFID out +Tim15, Tim1 + +## RFID pull +Tim15, Tim1, Tim8 + +## iButton +Tim3, Tim8 diff --git a/wiki/hw/Hardware-specification.md b/wiki/hw/Hardware-specification.md new file mode 100644 index 000000000..cf34bd74a --- /dev/null +++ b/wiki/hw/Hardware-specification.md @@ -0,0 +1,90 @@ +### Display + +* Monochrome LCD +* Resolution: 128х64px +* Diagonal: 1.4” +* Orange LED backlight + +### LED + +RGB LED + +### Control + +* 5-button joystick +* Back button +* Reboot — Back+Left buttons for 2 seconds + +### MCU + +* ARM® Cortex®-M4 +* 64 MHz +* 1MB (1M x 8) FLASH + +### Sub-1 GHz Range + +* СС1101 +* TX/RX +* Frequency: 433/434/315/868 Mhz +* Modulation: ASK/FSK + +### USB + +* 1x USB 2.0 port, type C +* USB device +* Charging + +### GPIO + +* 0.65mm Female Header Connectors with 2.54 pitch +* x12+ — Data pins / 5V tolerant +* 2x — GND +* 1x — 3.3V +* 1x — 5V + +### 125 khz RFID + +* Supported protocols: EM-4100, HID Prox +* Operate modes: Reader/Writer/Emulator + +### iButton 1-Wire + +* Supported protocols: Dallas DS1990A, Cyphral, Metakom +* Operate modes: Reader/Writer/Emulator + +### InfraRed + +* Supported frequency: 36-40 kHz +* Operate modes: Reader/Emulator + +### Bluetooth + +* Bluetooth Low Energy 4.0+ +* STM32WB55 + +### NFC + +* Supported protocols: Mifare +* Operate modes: Reader/Emulator/Sniffer + +### Vibro + +* Type: Coin motor +* RPM: ≥10000 + +### Speaker + +* Type: Coin + +### Power and battery + +* Built-in not removable lithium‑ion battery 2000mAh +* USB charging 5V, 500-2000mA +* ≥10 days standby + +### Physical + +* Materials: PC +* Weight: <200g +* Size: ~98х40х22mm +* Operating temperature: 0 ~ 50 °C \ No newline at end of file diff --git a/wiki/hw/Hardware-version-F1B1C0.0.md b/wiki/hw/Hardware-version-F1B1C0.0.md new file mode 100644 index 000000000..b3ef54efb --- /dev/null +++ b/wiki/hw/Hardware-version-F1B1C0.0.md @@ -0,0 +1,20 @@ +[Device schematic (pdf)](https://github.com/Flipper-Zero/wiki/raw/master/Flipper_zero_rev_1_0.pdf) + +## Errata + +* NAND reset IC drive reset net by push-pull output may cause MCU fault and disable internal MCU reset feature. +* System going to boot-loop state when reset by reset circuit +* No series resistors on external gpio for protecting MCU +* Wrong value LED series resistor +* Wrong footprint for CMOS transistors +* Wrong value IR TX series resistor +* No need capacitor on IR RX +* Wrong value IR RX pullup resistor +* 125 kHz RFID + iButton wrong schematic +* It seems bad to place main VCC on external GPIO pins. Overcurrent can damage main regulator and cause device broken. User can apply wrong voltage on this pin. + +### New RFID + iButton schematic + +after many experiments we found good schematic solution for work with RFID and auxiliary follow iButton level (for non-TTL protocol like Cyphral) + +![new RFID + iButton schematic](https://github.com/Flipper-Zero/wiki/raw/master/images/new-rfid-ibutton-sch.png) diff --git a/wiki/hw/Hardware-version-F2B0C1.1.md b/wiki/hw/Hardware-version-F2B0C1.1.md new file mode 100644 index 000000000..871d8a502 --- /dev/null +++ b/wiki/hw/Hardware-version-F2B0C1.1.md @@ -0,0 +1,76 @@ +* Firmware target: F2 +* Body version: no body +* Interconnection version: 1 + +# Pinout: +| Pin | Mode | Define | Description | +|-|-|-|-| +| PC13 | EXTI13 | BUTTON_BACK | Button | +| PC14 | RCC_OSC32_IN | | 32768 kHz XTAL | +| PC15 | RCC_OSC32_OUT | | 32768 kHz XTAL | +| PH0 | RCC_OSC_IN | | 16 MHz XTAL | +| PH1 | RCC_OSC_OUT | | 16 MHz XTAL | +| PC0 | GPIO_Analog | | External GPIO | +| PC1 | GPIO_Analog | | External GPIO | +| PC2 | EXTI2 | CHRG | Charge state | +| PC3 | ADC1_IN4 | BATT_V | Battery voltage | +| PA0 | ADC1_IN5 | IR_RX | Infrared receiver | +| PA1 | EXTI1 | BUTTON_DOWN | Button | +| PA2 | GPIO_Output | DISPLAY_DI | Display | +| PA3 | TIM5_CH4 | SPEAKER | | +| PA4 | GPIO_Analog | | External GPIO | +| PA5 | GPIO_Analog | | External GPIO | +| PA6 | GPIO_Analog | | External GPIO | +| PA7 | GPIO_Analog | | External GPIO | +| PC4 | GPIO_Output | NFC_CS | NFC SPI CS | +| PC5 | COMP1_INP | RFID_RF_IN | 125 kHz RFID RX, contact keys analog input (for Cyfral/metakom) | +| PB0 | EXTI0 | BUTTON_UP | Button | +| PB1 | GPIO_Output | LED_BLUE | Led | +| PB2 | GPIO_Analog | | External GPIO | +| PB10 | GPIO_Output | DISPLAY_RST | Display | +| PB11 | GPIO_Output | IR_TX | Infrared transmit | +| PB12 | GPIO_Analog | | External GPIO | +| PB13 | TIM15_CH1N | RFID_OUT | RFID 125 kHz read master tone/write TX | +| PB14 | GPIO_Output | LED_GREEN | Led | +| PB15 | TIM15_CH2 | RFID_PULL | RFID 125 kHz write/emulate pulling | NFC IRQ | +| PC6 | GPIO_Output | VIBRO | | +| PC7 | TIM8_CH2 | iButton | contact key | +| PC8 | GPIO_Output | DISPLAY_CS | Dispay | +| PC9 | GPIO_Output | SD_CS | microSD card SD | +| PA8 | GPIO_Output | LED_RED | Led | +| PA9 | USART1_TX | | External GPIO/USART TX | +| PA10 | USART1_RX | | External GPIO/USART RX | +| PA11 | USB_OTG_FS_DM | | USB | +| PA12 | USB_OTG_FS_DP | | USB | +| PA13 | SWDIO | | External GPIO/SWDIO | +| PA14 | SWCLK | | External GPIO/SWDCLK | +| PA15 | GPIO_Output | CC1101_CS | CC1101 CS | +| PC10 | SPI3_SCK | | SD/CC1101/NFC SPI | +| PC11 | SPI3_MISO | | SD/CC1101/NFC SPI | +| PC12 | SPI3_MOSI | | SD/CC1101/NFC SPI | +| PD2 | GPIO_Analog | | External GPIO | +| PB3 | SPI1_SCK | | Display | +| PB4 | EXTI4 | BUTTON_LEFT | Button | +| PB5 | SPI1_MOSI | | Display | +| PB6 | GPIO_Output | DISPLAY_BACKLIGHT | | +| PB7 | GPIO_Input | CC1101_G0 | | +| PB8 | EXTI8 | BUTTON_RIGHT | Button | +| PB9 | EXTI9 | BUTTON_OK | Button | + +# External GPIO + +| Pin | | | | | | +|-|-|-|-|-|-| +| PC0 | GPIO | LPUART RX | ADC1/2/3-1 | I²C SCL | | +| PC1 | GPIO | LPUART TX | ADC1/2/3-2 | I²C SDA | | +| PA4 | GPIO | DAC1-1 | ADC1/2-9 | SPI1 NSS | | +| PA5 | GPIO | DAC1-2 | ADC1/2-10 | SPI1 SCK | TIM2/8 OUT | +| PA6 | GPIO | | ADC1/2-11 | SPI1 MISO | TIM3/16 OUT | +| PA7 | GPIO | | ADC1/2-12 | SPI1 MOSI | TIM1/2/8/17 OUT | +| PB2 | GPIO | | | | RTC Alarm | +| PB12 | GPIO | | | | | +| PA9 | GPIO | USART1 TX | | | | +| PA10 | GPIO | USART1 RX | | | | +| PA13 | GPIO | SWDIO | | | | +| PA14 | GPIO | SWCLK | | | | +| PD2 | GPIO | UART5 RX | | | | \ No newline at end of file