diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..00a0191e5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# Welcome to FlipperZero contributing guide + +Thank you for investing your time in contributing to our project! + +Read our [Code of Coduct](CODE_OF_CONDUCT.md) to keep our community approachable and respectable. + +In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR. + +## New contributor guide + +See the [ReadMe](ReadMe.md) to get an overview of the project. Here are some helpful resources to get you comfortable with open source contribution: + +- [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github) +- [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git) +- [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) +- [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests) + +## Getting started + +Before writing code and creating PR make sure that it aligns with our mission and guidlines: + +- All our devices are intended for research and education. +- PR that contains code intended to commit crimes is not going to be accepted. +- Your PR must comply with our [Coding Style](CODING_STYLE.md) +- Your PR must contain code compatiable with project [LICENSE](LICENSE). +- PR will only be merged if it pass CI/CD. +- PR will only be merged if it pass review by code owner. + +Feel free to ask questions in issues if you're not sure. + +### Issues + +#### Create a new issue + +If you found a problem, [search if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments). If a related issue doesn't exist, you can open a new issue using a relevant [issue form](https://github.com/flipperdevices/flipperzero-firmware/issues/new/choose). + +#### Solve an issue + +Scan through our [existing issues](https://github.com/flipperdevices/flipperzero-firmware/issues) to find one that interests you. + +### Make Changes + +1. Fork the repository. +- Using GitHub Desktop: + - [Getting started with GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) will guide you through setting up Desktop. + - Once Desktop is set up, you can use it to [fork the repo](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)! + +- Using the command line: + - [Fork the repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) so that you can make your changes without affecting the original project until you're ready to merge them. + +2. Install build requirements + +3. Create a working branch and start with your changes! + +### Commit your update + +Commit the changes once you are happy with them. Make sure that code compilation is not broken and passes tests. Check syntax and formatting. + +### Pull Request + +When you're done making the changes, open a pull request, often referred to as a PR. +- Fill out the "Ready for review" template so we can review your PR. This template helps reviewers understand your changes and the purpose of your pull request. +- Don't forget to [link PR to issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if you are solving one. +- Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so the branch can be updated for a merge. +Once you submit your PR, a Docs team member will review your proposal. We may ask questions or request for additional information. +- We may ask for changes to be made before a PR can be merged, either using [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch. +- As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations). +- If you run into any merge issues, checkout this [git tutorial](https://lab.github.com/githubtraining/managing-merge-conflicts) to help you resolve merge conflicts and other issues. + +### Your PR is merged! + +Congratulations :tada::tada: The FlipperDevices team thanks you :sparkles:. diff --git a/GAMES_ONLY.md b/GAMES_ONLY.md new file mode 100644 index 000000000..5ab00c3a1 --- /dev/null +++ b/GAMES_ONLY.md @@ -0,0 +1,12 @@ +## Settings: Desktop=>Games Only (By RogueMaster) +- - DESKTOP LOOKS THE SAME WITH BATTERY AND IDLE ANIMATION +- - EXIT OF GAMES/CLOCK GOES BACK TO GAMES ONLY MODE +- - HOLD BACK TO TURN OFF FLIPPER +- - RESTARTING REMEMBERS YOU ARE IN GAMES ONLY MODE +- - CENTER OR HOLD DOWN FOR GAMES MENU (NOT WORKING) +- - HOLD CENTER TO CHANGE IDLE ANIMATION +- - UP OR HOLD UP FOR FAVORITE GAME (NOT WORKING) +- - LEFT OR HOLD LEFT FOR CLOCK (NOT PRIMARY/SECONDAY FAVORITE) +- - RIGHT ALWAYS WILL GO TO PASSPORT +- - Enter Games Only mode from Settings=>Desktop or from (Up Menu)Lock Menu=>GAMES ONLY +### FROM CLOCK: UP UP DOWN DOWN LEFT RIGHT LEFT RIGHT - EXIT GAME MODE diff --git a/MACOS_GUIDE.md b/MACOS_GUIDE.md new file mode 100644 index 000000000..16557d71d --- /dev/null +++ b/MACOS_GUIDE.md @@ -0,0 +1,103 @@ +# **macOS compile guide** by deafbed +### Tested with M1 Macbook Air, macOS Monterey (12.4) + +* *(NB: do NOT include the "$ " if copying/pasting any of the below commands)* + +## FROM SCRATCH + +### Install qFlipper +qFlipper can be found on the App Store or you can download it from [https://flipperzero.one/update](https://flipperzero.one/update) + +### Install Brew +Open Terminal.app and run + +`$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` + +**IMPORTANT:** once installed, run the two commands given to you ("Next steps") + +*(first should begin `$ echo 'eval...'`, second should begin `$ eval "$(/opt/...))`* + +Quit and re-open Terminal.app, then run + +`$ brew help` + +to check if the installation was successful + +### Install Docker Desktop +Download the appropriate version (Intel/M1) of Docker Desktop from +[https://docs.docker.com/desktop/mac/install/](https://docs.docker.com/desktop/mac/install/) + +*(If the downloaded file has no extension/won't open, simply append .dmg to the filename)* + +Open Docker.dmg and drag Docker.app to the Applications folder + +Eject Docker.dmg from the sidebar, navigate to your Applications folder and open Docker. Install as prompted and wait a few seconds until Docker is running + +Quit and re-open Terminal, and run + +`$ docker help` + +to check if the install was successful + + +### Make sure PIP is up-to-date +Still in Terminal, run + +`$ python3 -m pip install --upgrade pip` + +### Download the firmware +Next, run + +`$ git clone --recursive https://github.com/RogueMaster/flipperzero-firmware-wPlugins.git` + +This will download the latest build files from the github repository (in this case most likely to your Home folder) + +### Install the necessary prerequisites +Navigate to the folder you just downloaded + +`$ cd flipperzero-firmware-wPlugins` + +Next, we run 2 scripts to download the remaining requirements. First: + +`$ brew bundle --verbose` + +Then: + +`$ pip3 install -r scripts/requirements.txt` + +### Compile +Make sure Docker is still open, if not open Docker.app + +In Terminal, still in the flipperzero-firmware-wPlugins directory, run + +`$ docker-compose up -d` + +Then: + +`$ docker-compose exec dev ./fbt` + +It may take a while and you might see some errors but if all goes well the compiled firmware (DFU) file should now be in **flipperzero-firmware-wPlugins/dist/f7-C/flipper-z-f7-full-local.dfu** + +### Put your Flipper into Recovery/DFU mode +Put your flipper into DFU mode by: + +1. holding BACK + LEFT until it turns off +2. once turned off, release BACK but keep holding LEFT until the LED flashes blue +3. once the LED flashes blue, release LEFT and your Flipper should be in recovery mode + +### Install the firmware +Open qFlipper.app + +Connect your Flipper via USB + +In qFlipper, click "Install from file" (underneath the big INSTALL button) + +Navigate to your DFU file (**flipperzero-firmware-wPlugins/dist/f7-C/flipper-z-f7-full-local.dfu**) + +Wait for the process to finish. If your Flipper device is no longer in DFU mode (i.e. shows the normal Desktop), unplug your Flipper and close the qFlipper app + +### Post-Install +Open qFlipper.app and connect your Flipper via USB + +If everything worked, your Flipper should be recognized and the firmware version should match the github commit shown here: +[https://github.com/RogueMaster/flipperzero-firmware-wPlugins](https://github.com/RogueMaster/flipperzero-firmware-wPlugins) diff --git a/RoadMap.md b/RoadMap.md new file mode 100644 index 000000000..0cf95331d --- /dev/null +++ b/RoadMap.md @@ -0,0 +1,82 @@ +# RoadMap for RM BUILD +### This is more of a project wish list... +- It is open to whomever wants to build and PR. You get all the credit if you can create it! :D +- I likely won't have time to cover all these items. +- Some of these would make great sample projects to learn how to make apps for flipper. +- I tried to organize them in terms of difficulty. + +## WISH LIST ITEMS: +- `Notepad` APP to allow taking quick notes and saving to SD. +- - Also can possibly open/edit .md,.txt,.fmf and other text friendly formats +- `UART` Move UART Echo app from Debug to GPIO section. +- `Write URL to NFC` APP to allow creating URL NFC tags from only the flipper +- - Also can possibly support larger URLs than the ones in samples (due to length limits on NFC types) +- - Also can possibly create other types of tags, like WIFI configurations +- `Doplhin SubGHz Chat` APP to allow listening for and viewing SubGHz messages and sending SubGHz messages +- - Could also be set to transmit a message every X seconds/minutes until another Flipper responds +- `Bluetooth Audio` APP to allow flipper to pair to external speaker or headphones for mp3 playback +- - Also can possible pair to speaker via NFC tap, here are some possible resources: +- - - https://github.com/urish/circuitpython-mp3-ble +- - - https://github.com/averyling82/wifi-bt-audio +- - - https://github.com/YetAnotherElectronicsChannel/ESP32_Bluetooth_Audio_Receiver +- - - https://github.com/redchenjs/bluetooth_visual_speaker_esp32 +- - - https://github.com/cefali9154/BluetoothPlayer +- - - https://github.com/jujax/lyrat_passthru +- - Also can support playlists / playlist files +- `Bluetooth OpenHayStack` for Flipper, changes current bluetooth configuration to transmit Bluetooth Open Haystack packet as needed for the device to be findable when settings for Bluetooth is set to ON in settings and OpenHayStack is set to ON in settings. +- - Not sure if could possiblt also serve to find devices +- - Example resource of OpenHayStack as an alternative to Bluetooth On/Off: https://github.com/AlexStrNik/flipperzero-firmware/tree/dev +- `Tamagochi` Save State +- Skip to next or previous SubGHz scan file from emulation screen using UP/DOWN + +# +# +# RoadMap for ORIGINAL FIRMWARE +# Where we are (0.x.x branch) +Our goal for 0.x.x branch is to build stable usable apps and API. +First public release that we support in this branch is 0.43.1. Your device most likely came with this version. +You can develop applications but keep in mind that API is not final yet. + +## What's already implemented + +**Applications** + +- SubGhz: all most common protocols, reading RAW for everything else +- 125kHz RFID: all most common protocols +- NFC: reading/emulating Mifare Ultralight, reading MiFare Classic and DESFire, basic EMV, basic NFC-B,F,V +- Infrared: all most common RC protocols, RAW format for everything else +- GPIO: UART bridge, basic GPIO controls +- iButton: DS1990, Cyfral, Metacom +- Bad USB: Full USB Rubber Ducky support, some extras for windows alt codes +- U2F: Full U2F specification support + +**Extras** + +- BLE Keyboard +- Snake game + +**System and HAL** + +- Furi Core +- Furi HAL + +# Where we're going (Version 1) + +Main goal for 1.0.0 is to provide first stable version for both Users and Developers. + +## What we're planning to implement in 1.0.0 + +- Loading applications from SD (tested as PoC, work scheduled for Q2) +- More protocols (gathering feedback) +- User documentation (work in progress) +- FuriCore: get rid of CMSIS API, replace hard real time timers, improve stability and performance (work in progress) +- FuriHal: deep sleep mode, stable API, examples, documentation (work in progress) +- Application improvements (a ton of things that we want to add and improve that are too numerous to list here) + +## When will it happen and where I can see the progress? + +Release 1.0.0 will most likely happen around the end of Q3 + +Development progress can be tracked in our public Miro board: + +https://miro.com/app/board/uXjVO_3D6xU=/?moveToWidget=3458764522498020058&cot=14 diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 000000000..9f96dbe3b --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,10 @@ + +
[FLIPPER PROJECT WISH LIST](https://github.com/RogueMaster/flipperzero-firmware-wPlugins/blob/420/RoadMap.md) - [SAMPLE EDUCATIONAL PROJECTS 😄](https://github.com/RogueMaster/flipperzero-firmware-wPlugins/blob/420/RoadMap.md) + +

DONATIONS ACCEPTED 😄🚀💸

+BTC: 3MPQbKmGRCstg4FjnadfHa3woCT94JkR2a
+ETH: 0xC32Ea488DBeCF95992A5C81BD411e56Bd418BC5f +

+ +Contact me on [Discord](https://discord.gg/gF2bBUzAFe) if you want a renamed Flipper DFU. I can do custom names too! +

[Join my Flipper/Amiibo Discord](https://discord.gg/gF2bBUzAFe)