Skip to content

Commit

Permalink
Expanded README.MD
Browse files Browse the repository at this point in the history
  • Loading branch information
@janwiesemann
janwiesemann committed Dec 14, 2024
1 parent 8a613b5 commit 60b4404
Show file tree
Hide file tree
Showing 4 changed files with 119 additions and 24 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@ dist/*
.editorconfig
.env
.ufbt
!.vscode/extensions.json
21 changes: 21 additions & 0 deletions .vscode/extensions.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
// List of extensions which should be recommended for users of this workspace.
"recommendations": [
"ms-python.black-formatter",
"llvm-vs-code-extensions.vscode-clangd",
"amiralizadeh9480.cpp-helper",
"marus25.cortex-debug",
"zxh404.vscode-proto3",
"augustocdias.tasks-shell-input",
"rioj7.command-variable",
"yzhang.markdown-all-in-one"
],
// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
"unwantedRecommendations": [
"twxs.cmake",
"ms-vscode.cpptools",
"ms-vscode.cmake-tools"
]
}
80 changes: 76 additions & 4 deletions README.MD
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,63 @@
# Flipper SPI Terminal
# Flipper SPI Terminal <!-- omit in toc -->

![Main Menu](screenshots/screen_main.png)

SPI TERMINAL is a SPI App, which allows you to control external devices using SPI. Your Flipper can act as a SPI Master or Slave device. The Slave mode allows you to sniff the communication between different SPI peripherals.

The App uses the Low-Level SPI Interface of the STM32WB55RG Microprocessor. All data is transmitted with DMA Sub-module and can reach speeds of up to 32 Mbit/s in Master and up to 24 Mbit/s in Slave mode.

It contains a rich [Inbuilt Documentation](#inbuilt-documentation).

![Config Screen - Help](screenshots/screen_config_help.png)

> [!IMPORTANT]
> The current version does not support the sending of data. This is planned for future versions.
> [!IMPORTANT]
> Flipper SPI Terminal requires full control over Flipper Zero's `SPI Bus R`/`SPI1`. Due to this, all access to it and it's connected peripherals is blocked up on entering the Terminal Screen. This includes access to the SD-Card. All SD accesses (i.e.: qFlipper, lab.flipper.net, iOS/Android App) will result in a crash and you'll need to reset you Flipper by simultaneously holding down the `Left` and `Back` buttons.
## Contents <!-- omit in toc -->

- [Installation](#installation)
- [Flipper Apps Catalog](#flipper-apps-catalog)
- [GitHub (Recommended)](#github-recommended)
- [Building Flipper SPI Terminal](#building-flipper-spi-terminal)
- [GPIO](#gpio)
- [Configuration](#configuration)
- [Terminal Screen](#terminal-screen)
- [Inbuilt Documentation](#inbuilt-documentation)
- [CLI](#cli)
- [Contribute/Debugging](#contributedebugging)
- [External References](#external-references)

## Installation

### Flipper Apps Catalog

> [!IMPORTANT]
> The app has been [submitted to the Flipper Apps Catalog](https://github.com/flipperdevices/flipper-application-catalog/pull/577) but it hasn't yet been accepted.
### GitHub (Recommended)

1. Head over to the [Releases](https://github.com/janwiesemann/flipper-spi-terminal/releases) section
2. Download the latest `flipper_spi_terminal.fap`
3. Place `flipper_spi_terminal.fap` on your microSD's `/apps/GPIO/` folder.

### Building Flipper SPI Terminal

1. Install [uFBT](https://github.com/flipperdevices/flipperzero-ufbt) and [git](https://git-scm.com).
2. Open a commandline and navigate to a directory of your liking.
3. Connect Flipper Zero to your computer using a USB cable.
> [!NOTE]
> If you just want to build Flipper SPI Terminal but don't want to install it, change the last command, from the next step, from `ufbt launch` to `ufbt`.
4. Run the following command(s) to clone, build and install Flipper SPI Terminal to your Flipper Zero.

```bash
git clone https://github.com/janwiesemann/flipper-spi-terminal.git
cd flipper-spi-terminal
ufbt launch
```

## GPIO

> [!CAUTION]
Expand All @@ -30,22 +76,36 @@ It contains a rich [Inbuilt Documentation](#inbuilt-documentation).
SPI Terminal offers access to all of the Flipper Zero SPI settings. Your configuration will be reloaded on the next launch. The config file is located at `/ext/apps_data/flipper_spi_terminal/last_settings.settings`.

> [!TIP]
> The full list of configuration options found in [`flipper_spi_terminal_config_declarations.h`.](https://github.com/janwiesemann/flipper-spi-terminal/blob/master/flipper_spi_terminal_config_declarations.h)
> The full list of configuration options found in [`flipper_spi_terminal_config_declarations.h`](https://github.com/janwiesemann/flipper-spi-terminal/blob/master/flipper_spi_terminal_config_declarations.h).

![Config Screen](screenshots/screen_config.png)

> [!NOTE]
> A few advanced settings can only be accessed though the Flipper CLI. Please refer to the [CLI](#cli) section for details.


## Terminal Screen

The Terminal Screen is the main part of this application. Is can display received data in multiples modes. Currently they are `Auto`, `Text`, `Hex` and `Binary`.
The Terminal Screen is the main part of this application. Is can display received data in multiples modes. Currently they are:

- **Auto:**
Printable chars are rendered. Special chars (`\ ` (space), `\n`, `\r`, ...) are rendered using there C escape sequence. Everything else is rendered as Hex.
![Terminal Screen - Auto Mode](screenshots/screen_terminal_auto.png)
- **Text:**
Printable chars are rendered. Non-printable are rendered as empty space.
![Terminal Screen - Text Mode](screenshots/screen_terminal_text.png)
- **Hex:**
![Terminal Screen - Hex Mode](screenshots/screen_terminal_hex.png)
- **Binary:**
![Terminal Screen - Binary Mode](screenshots/screen_terminal_binary.png)

New data is added in a rolling buffer. This means, that the screen can be rendered without the need of copying huge amounts of data.

## Inbuilt Documentation

Flipper SPI Terminal contains a inbuilt documentation for each configuration setting. It can be accessed though the `Center` button on the configuration screen.

![Config Screen - Help](screenshots/screen_config_help.png)

> [!NOTE]
> For a deeper understanding of all the configuration options and there affect, I would recommend the [STM Reference Manual RM0434](https://www.st.com/resource/en/reference_manual/rm0434-multiprotocol-wireless-32bit-mcu-armbased-cortexm4-with-fpu-bluetooth-lowenergy-and-802154-radio-solution-stmicroelectronics.pdf). The SPI-Section (`Section 35.`) is located on page `1177`.

Expand All @@ -58,6 +118,16 @@ A list of commands and there uses can be printed with `spi help`
> [!TIP]
> A full list can also be found in [`flipper_spi_terminal_cli_commands.h`](https://github.com/janwiesemann/flipper-spi-terminal/blob/master/flipper_spi_terminal_cli_commands.h).

## Contribute/Debugging

Feel free to contribute to Flipper SPI Terminal and to submit a Pull request. Make sure you're adding a reference to your contribution into the about scene located at `scenes/scene_about.c` (`const char* about_text = "..."`).
I heavily recommend the use of a debugging probe. The [WiFi Devboard for Flipper Zero](https://shop.flipperzero.one/products/wifi-devboard) isn't a good choice, since It's connecting the SPI pins to the ESP32. This can cause some issues. Generally, Flippers SPI pins do not overlap with the SWD pins, enabling the use of a SPI and SWD probe at the same time. I'm using a SEGGER J-Link probe but there are certainly cheaper options available. Only using Flipper Zero's Logging system is not really feasible, since they are not working in interrupts and often lack behind the actual execution point.
For development purposes it's a good idea to use a SPI dive you can fully control. I'm using a WeMos D1 clone for this. The Arduino sketches are located in `ext_test_app/`.
A few purpose built debug commands are available though the Flipper CLI. See [CLI](#cli) for details.
## External References
- **STM32F7 SPI presentation:**
Expand All @@ -70,3 +140,5 @@ A list of commands and there uses can be printed with `spi help`
<https://docs.flipper.net/gpio-and-modules>
- **Flipper Zero CLI:**
<https://docs.flipper.net/development/cli>
- **Flipper uFBT:**
<https://github.com/flipperdevices/flipperzero-ufbt>
41 changes: 21 additions & 20 deletions scenes/scene_about.c
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,30 @@
#include "scenes.h"
#include "../flipper_spi_terminal.h"

const char* about_text =
"SPI TERMINAL\n"
"\n"
"By JAN WIESEMANN.de\n"
"https://github.com/janwiesemann/flipper-spi-terminal\n"
"\n"
"SPI TERMINAL is a SPI App, which allows you to control external devices using SPI. Your Flipper can act as a SPI Master or Slave device. The Slave mode allows you to sniff the communication between different SPI peripherals.\n"
"\n"
"The App uses the Low-Level SPI Interface of the STM32WB55RG Microprocessor. All data is transmitted with DMA Sub-module and can reach speeds of up to 32 Mbit/s in Master and up to 24 Mbit/s in Slave mode.\n"
"\n"
"The inbuild documentation is based on the 'STM32F7 - SPI' (Revision 1.0) presentation and the STM 'RM0434' Reference Manual. Both referenced are linked to in the GitHub README.MD."
"\n"
"=== Pin configuration ===\n"
"CAUTION: Flipper Zero's pins are only 5V tolerant, if they are configured as an input. Due to this limitation, only 3.3V signals should be used!\n"
"\n"
"MOSI: 2 (PA7) Master In / Slave Out\n"
"MISO: 3 (PA6) Master Out / Salve In\n"
" CS: 4 (PA4, NSS) Non Slave Select\n"
" SCK: 5 (PB3) Serial Clock";

void flipper_spi_terminal_scene_about_alloc(FlipperSPITerminalApp* app) {
app->about_screen = text_box_alloc();

text_box_set_text(
app->about_screen,
"SPI TERMINAL\n"
"\n"
"By JAN WIESEMANN.de\n"
"https://github.com/janwiesemann/flipper-spi-terminal\n"
"\n"
"SPI TERMINAL is a SPI App, which allows you to control external devices using SPI. Your Flipper can act as a SPI Master or Slave device. The Slave mode allows you to sniff the communication between different SPI peripherals.\n"
"\n"
"The App uses the Low-Level SPI Interface of the STM32WB55RG Microprocessor. All data is transmitted with DMA Sub-module and can reach speeds of up to 32 Mbit/s in Master and up to 24 Mbit/s in Slave mode.\n"
"\n"
"The inbuild documentation is based on the 'STM32F7 - SPI' (Revision 1.0) presentation and the STM 'RM0434' Reference Manual. Both referenced are linked to in the GitHub README.MD."
"\n"
"=== Pin configuration ===\n"
"CAUTION: Flipper Zero's pins are only 5V tolerant, if they are configured as an input. Due to this limitation, only 3.3V signals should be used!\n"
"\n"
"MOSI: 2 (PA7) Master In / Slave Out\n"
"MISO: 3 (PA6) Master Out / Salve In\n"
" CS: 4 (PA4, NSS) Non Slave Select\n"
" SCK: 5 (PB3) Serial Clock");
text_box_set_text(app->about_screen, about_text);

view_dispatcher_add_view(
app->view_dispatcher,
Expand Down

0 comments on commit 60b4404

Please sign in to comment.