{"id":47625009,"url":"https://github.com/bluerobotics/ping-firmware-oss","last_synced_at":"2026-04-01T22:43:45.616Z","repository":{"id":288408451,"uuid":"916617304","full_name":"bluerobotics/ping-firmware-oss","owner":"bluerobotics","description":"Open Source firmware implementation for Ping Echosounder","archived":false,"fork":false,"pushed_at":"2025-04-25T18:27:15.000Z","size":2449,"stargazers_count":5,"open_issues_count":4,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-25T19:31:31.980Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bluerobotics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-14T13:00:35.000Z","updated_at":"2025-04-25T18:27:19.000Z","dependencies_parsed_at":"2025-04-18T00:46:33.781Z","dependency_job_id":"c33cadf0-dd65-4267-a9ae-4da004379b19","html_url":"https://github.com/bluerobotics/ping-firmware-oss","commit_stats":null,"previous_names":["bluerobotics/ping-firmware-oss"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/bluerobotics/ping-firmware-oss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluerobotics%2Fping-firmware-oss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluerobotics%2Fping-firmware-oss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluerobotics%2Fping-firmware-oss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluerobotics%2Fping-firmware-oss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluerobotics","download_url":"https://codeload.github.com/bluerobotics/ping-firmware-oss/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluerobotics%2Fping-firmware-oss/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-01T22:43:42.920Z","updated_at":"2026-04-01T22:43:45.606Z","avatar_url":"https://github.com/bluerobotics.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Open Source Sonar (OSS) Firmware for Ping1D Echosounder Devices\n\n## Contents\n\n1. [Context and inspiration](#context-and-inspiration)\n1. [Current functionality](#current-functionality)\n1. [Installation](#installation)\n1. [Standard operation](#standard-operation)\n   1. [Filtering and processing](#filtering-and-processing)\n   1. [Distance estimation](#distance-estimation)\n   1. [Communication and interfacing](#communication-and-interfacing)\n1. [Reference hardware](#reference-hardware)\n   1. [Known compatible devices](#known-compatible-devices)\n   1. [Main control connections](#main-control-connections)\n   1. [Amplification and filtering (Analog Sector)](#amplification-and-filtering-analog-sector)\n   1. [Sensing](#sensing)\n1. [Development and contributions](#development-and-contributions)\n   1. [Firmware overview](#firmware-overview)\n   1. [Configuration](#configuration)\n   1. [Dependencies](#dependencies)\n   1. [Building the firmware](#building-the-firmware)\n   1. [Flashing the device](#flashing-the-device)\n1. [Project history](#project-history)\n\n\n## Context and inspiration\n\nWhen exploring and measuring the underwater environment, [sonar technologies](https://bluerobotics.com/learn/a-smooth-operators-guide-to-underwater-sonars-and-acoustic-devices/) are invaluable, and just plain cool!\n\nRecent advancements have made sonar devices cheaper and more accessible, but proprietary hardware and software designs mean they're generally still hard to play and experiment with, and research applications like custom algorithms and transducer designs are difficult to set up, test, and compare. While we can dream of a world of open source sonar devices, even a single transducer can enable many use-cases, so let's start there!\n\n\u003e As a few examples from the Blue Robotics forums, consider possibilities like:\n\u003e - [Acoustic beacons](https://discuss.bluerobotics.com/t/recovering-research-equipment-after-6months-with-bluerov2/12299/2) for equipment recovery\n\u003e - Exploring [acoustic positioning](https://discuss.bluerobotics.com/t/best-way-to-determine-distance-between-multiple-bluerovs/8474/2)\n\u003e - [Measuring acoustic attenuation of the environment](https://discuss.bluerobotics.com/t/raw-profile-data-from-ping1d/12425/6)\n\u003e - [Oceanographic water property sensing](https://discuss.bluerobotics.com/t/raw-profile-data-from-ping1d/12425/5)\n\u003e - [Basic scanning sonar](https://discuss.bluerobotics.com/t/using-ping1d-and-servo-with-arduino-nano-every/11715)\n\u003e - [Echosounder distance tracking algorithms](https://discuss.bluerobotics.com/t/interpretation-of-sonar-raw-data/11722/4)\n\u003e - Anti-synchronisation for [obstacle avoidance](https://discuss.bluerobotics.com/t/suitability-of-ping-sonar-in-caves/11655)\n\nDeveloping useful devices and algorithms takes a lot of work, so it makes sense to limit the initial project scope by building upon existing projects and standards. As a starting point, there are existing open communication protocols available for some common use-cases, and using them can provide guidelines for functionality that should be implemented, while also allowing for expansion as new use-cases are explored, and connecting to existing display/control software that's compatible with those protocols. There are also purchaseable devices that already solve many of the physical challenges of operating sonar underwater, which could have their existing functionalities substantially expanded by an open source, general purpose sonar firmware.\n\n\n## Current functionality\n\n\u003e 💡 **This project is intended as a learning resource**, and as an entryway for playing with / testing sonar technologies.\n\n\u003e ⚠️ Interfacing with existing device electronics was [done through reverse engineering](#project-history), so cannot be guaranteed to be correct/identical.\n\u003e\n\u003e Without affiliation with the original device designers or developers, outputs from this project cannot be recognised as official replacement firmware for devices it happens to be compatible with.\n\nImplemented features include:\n- Acoustic mono-frequency pulse transmission\n   - e.g. for a beacon/pinger\n- Acoustic receiving\n   - e.g. for a hydrophone / for testing beam width of other sonars\n- [Basic signal processing](#filtering-and-processing), to improve data scaling and interpretability\n- Sonar and echosounding\n   - [Distance estimation](#distance-estimation), for surface/target tracking or obstacle avoidance\n   - Compatibility with [`ping-protocol`'s echosounding messages](#communication-and-interfacing), implemented on an STM32 microcontroller\n\n\n## Installation\n\n\u003e 💡 Pre-built firmware binaries are available in the assets of the [releases](https://github.com/bluerobotics/ping-firmware-oss/releases), and as artifacts of automated [actions](https://github.com/bluerobotics/ping-firmware-oss/actions) that run when code is added to the repository or submitted as a pull request.\n \nInstallation can typically be performed [using Ping Viewer](https://docs.bluerobotics.com/ping-viewer/firmware-update/#manual-firmware-update), or more directly [using the stm32flash tool](https://docs.bluerobotics.com/ping-viewer/firmware-update/#ping-sonar-device-recovery). There are more details in the [flashing the device](#flashing-the-device) section.\n\n\n## Standard operation\n\nAfter relevant setup of the hardware, the firmware is responsible for transmitting pulses, receiving and processing the echo signals (after an optional delay), and sending processed data to the host computer. A more detailed breakdown is included in the [Firmware Overview](#firmware-overview) section.\n\n### Filtering and processing\n\nAfter any [electrical filtering provided by the hardware](#amplification-and-filtering-analog-sector), the measured sound signals are [processed](https://github.com/search?q=repo%3Abluerobotics%2Fping-firmware-oss+void+PingSonar%3A%3AprocessProfile+path%3Asonar.cpp\u0026type=code) into squared sequential differences, then normalised, before the full-rate samples are sub-sampled (by maximum-value selection) into the number of points being communicated in a profile.\n\n\u003e 💡 In future it makes sense to add a software-based frequency filter, to prioritise sound samples that match a target frequency (e.g. the frequency of the transmitted pulses, to improve echo detection).\n\n### Distance estimation\n\nDistances are estimated using a [peak detection algorithm](https://github.com/ES-Alexander/ping-firmware-oss/blob/the-easy-thing/firmware/Core/Src/DSP/echo_finder.c) that runs on the measured samples (prior to profile sub-sampling), after finding and excluding the device's resonant ringing period after a transmit pulse.\n\n### Communication and interfacing\n\nFull-compatibility is provided with the [`common`](https://docs.bluerobotics.com/ping-protocol/pingmessage-common/) and [`ping1d`](https://docs.bluerobotics.com/ping-protocol/pingmessage-ping1d/) message sets of the open-source [Ping Protocol](https://docs.bluerobotics.com/ping-protocol/) for sonar devices.\n\nAs a result, sonars running the firmware can be readily interfaced with the following:\n- **Applications:**\n   - (Blue Robotics) [Ping Viewer](https://docs.bluerobotics.com/ping-viewer)\n   - (Cerulean) [SonarView](https://ceruleansonar.com/sonarview/)\n- **Devices:**\n   - flight controller boards running ArduSub / ArduRover autopilots, [as a rangefinder](https://ardupilot.org/rover/docs/common-bluerobotics-ping.html)\n- **Software libraries:**\n   - [Arduino](https://github.com/bluerobotics/ping-arduino)\n   - [C++](https://github.com/bluerobotics/ping-cpp)\n   - [Python](https://github.com/bluerobotics/ping-python)\n   - [Rust](https://github.com/bluerobotics/ping-rs)\n\n\n## Reference hardware\n\nA viable hardware example has been determined by reverse-engineering a Blue Robotics Ping Sonar PCB** into the following high level schematic:\n\u003cimg src=\"./docs/high_level.svg\" alt=\"High-level example hardware diagram, from the Blue Robotics Ping Sonar\" width=\"100%\"\u003e\n\n\u003e ****NOTE:** The Ping Sonar is known to work for at least echosounding purposes (as that is what it is sold as), but general design tradeoffs are not commented on as they were not the focus of [the reverse-engineering analysis](#project-history).\n\n### Known compatible devices\n- [Original Ping Sonar](https://web.archive.org/web/20230330171011/https://bluerobotics.com/store/sensors-sonars-cameras/sonar/ping-sonar-r2-rp/) from Blue Robotics\n    - Advertised with a 30 degree beamwidth, 115kHz transducer frequency, 300m depth rating, and 0.5-50m range*\n- [Second generation Ping Sonar](https://bluerobotics.com/store/sonars/echosounders/ping-sonar-r2-rp/) from Blue Robotics\n    - Advertised with a 25 degree beamwidth, 115kHz transducer frequency, 300m depth rating, and 0.3-100m range*\n    - **PCB [used as a reverse-engineering target](#project-history) when developing this firmware**\n\n\u003e ***NOTE:** Advertised usable range is indicative of hardware capabilities - matching values cannot be guaranteed with this open source firmware because the official firmware uses proprietary (i.e. unknown) processing and estimation algorithms\n\n### Main control connections\n\nThe reference hardware uses an [STM32F303RET6](https://www.st.com/resource/en/datasheet/stm32f303re.pdf) MCU (microcontroller) from STMicroelectronics, which manages all key functionalities of the sonar, including:\n\n- Generating the sonar pulse (on pin `PC6`)\n   - Achieved in this firmware using a PWM (Pulse-Width Modulation) output, with its signal generated by **Advanced Timer 8 (`TIM8`)** on **Channel 1**\n- Receiving the echo signal (on pin `PB15`)\n   - Captured using **ADC4 Channel 5**, which is a Fast Channel\n- Processing the received signal\n\nCommunication between the MCU and the host computer occurs via a serial interface.\n\n### Amplification and filtering (Analog Sector)\n\nThe amplification and filtering of the received signal are proprietary and have been kept closed-source to avoid any potential violation of the sonar's intellectual property rights. The only information that this document shares is that the received signal is filtered using a band-pass filter centered around the transmission frequency of **115 kHz**.\n\nFor the firmware, it is important to note that the analog sector shares some functionality with the internal operational amplifiers (OPAMPs) of the MCU. The following details are relevant:\n\n- **OPAMPs 2 and 3:** Configured in PGA (Programmable Gain Amplifier) mode for gain control.\n- **OPAMP 4:** Configured in standalone mode for bias (offset adjustment), working in conjunction with the internal DAC.\n\nThe pin configurations for these OPAMPs are available in the [high-level schematic](#reference-hardware).\n\n### Sensing\n\nThe sonar board is equipped with sensing capabilities that allow some measurements to be performed. The available sensing points include:\n\n- **PCB Temperature Sensing:** Available on `PA2` (**ADC1 Channel 3**).\n- **Supply Voltage (5V) Sensing:** Available on `PC2` (**ADC1 Channel 8**).\n- **Internal Processor Temperature Sensing:** Accessible via the **ADC1 Temperature Sensor channel**.\n\n\n## Development and contributions\n\n\u003e 💡 **Code is provided as-is** (under an [MIT license](/LICENSE)), and not actively _supported_, but pull requests with improvements and new features are welcome.\n\nThe firmware is developed using the STM32 CubeMX tool for initialization and configuration. It is written in C++, and is compiled using CMake and the GNU Arm Embedded Toolchain.\n\n### Firmware overview\n\nThe sonar usually operates in a cycle that consists of the following steps:\n  - **Transmitting a pulse:** The sonar generates a pulse using **TIM8** and sends it to the water.\n  - **Delay:** The sonar waits for a delay **TIM2** before starting to receive the echo signal if specified.\n  - **Receiving the echo signal:** The sonar receives the echo signal using **TIM1** and **ADC4**.\n  - **Processing the echo signal:** The sonar processes the echo signal using the DSP module.\n  - **Sending the data:** The sonar sends the processed data to the host computer.\n\nAs this firmware uses a separated buffer for UART communication, the sonar can be commanded to send the data at any time, not only after a full cycle. It can also start a new processing cycle immediately after finishing the previous one, without needing to wait for the data to be sent.\n\nThe code is organized as follows:\n\n1. [**Sonar Module**](/firmware/Core/Src/Sonar)\n   - Responsible for the core functionality of the echo sounder\n   - Manages the entire echo capture sequence—generating transmit pulses, handling echo reception, running digital signal processing (DSP), and providing real-time updates\n   - Centered around the `PingSonar` class in [sonar.cpp](/firmware/Core/Src/Sonar/sonar.cpp)\n1. **Board Module**\n   - Mainly responsible for managing the sensing aspects of the sonar, reading the supply voltage, PCB temperature, and internal processor temperature\n   - Includes some utilities to manage the interface with the hardware interface, mainly focused on the **go to bootloader** logic.\n   - Centered around the `SonarBoard` class in [board.cpp](/firmware/Core/Src/Sonar/board.cpp)\n1. **Server Module**\n   - Responsible for handling the communication between the sonar and the host computer\n   - Manages the serial communication, including receiving commands and sending data back to the host\n   - Centered around the `PingServer` class in [server.cpp](/firmware/Core/Src/Sonar/server.cpp)\n1. [**DSP Module**](/firmware/Core/Src/DSP)\n   - Responsible for processing the echo signal received by the sonar\n   - Unlike other modules, consists of a series of optimized functions that are used by the `PingSonar` class to process the echo signal\n   - Stored by default in the CCM (Core Coupled Memory) of the MCU, to ensure that it can be executed at the highest speed possible\n\n### Configuration\n\nThe sonar operational aspects can be configured using the [config.h](/firmware/Core/Inc/config.h) file. This file contains various parameters that can be adjusted to customize the sonar's behavior based on specific requirements. All parameters are documented in the file, making it easy to understand and modify the configuration.\n\n#### Timers\n\nTimers are the core components used to synchronize readings and generate the sonar pulse. This firmware leverages the STM32's interconnect matrix to automate and synchronize the sampling process. Transmission, delay, and reception are all timer-based and interconnected, allowing the firmware to initiate the process and wait for results to be processed using DSP (Digital Signal Processing) algorithms.\n\nThe timers utilized are the advanced timers **TIM8** and **TIM1**, and the 32-bit basic timer **TIM2**.\n\n---\n\n##### TIM8 (Advanced)\n\n\u003e Responsible for generating the sonar pulse, initiating the chain of events leading to the echo reception.\n\n**Configuration:**\n- **Clock Source:** PLLCLK2 at 144 MHz, providing high precision for pulse generation.\n- **Mode:** Configured in **one-pulse mode**, generating a specified number of pulses (determined by the repetition counter) and then stopping.\n- **PWM Output:**\n  - Channel: CH1\n  - Mode: PWM Mode 2\n  - Frequency: 115 kHz\n  - Duty Cycle: 50%\n- **Trigger Event Selection (TRGO):** Configured as **ENABLE**, allowing TIM8 to trigger **TIM2** in sync with the start of the pulse transmission.\n\n---\n\n##### TIM1 (Advanced)\n\n\u003e Controls the timing of each sample acquisition by triggering ADC4 to read the received echo signal.\n\n**Configuration:**\n- **Clock Source:** PLLCLK2 at 144 MHz, providing high precision.\n- **Mode:** Configured in **one-pulse mode**, generating a fixed number of pulses (determined by the repetition counter) and then stopping, resulting in a fixed number of samples.\n- **Trigger Event Selection 2 (TRGO2):** Configured as **Compare Pulse OC1**, used by ADC4 as the source trigger for conversions.\n\n---\n\n##### TIM2\n\n\u003e Acts as a delay generator between the pulse transmission and the start of the echo signal reception, used for the scan start delay.\n\n**Configuration:**\n- **Clock Source:** PLLCLK2 at 144 MHz, providing high precision.\n- **Mode:** Configured in **one-pulse mode**, generating a delay based on the repetition counter and then stopping.\n- **Trigger Event Selection (TRGO):** Configured as **Compare Pulse OC1**, triggering **TIM1** when the delay period ends.\n\n---\n\n#### ADCs\n\nAll ADCs use DMA (Direct Memory Access) for efficient data transfer. The configurations for the ADCs are detailed below:\n\n##### ADC1\n\n\u003e ADC1 handles the sensing channels for the sonar system. It operates in continuous mode with 12 bits precision and is configured as follows:\n\n**Configuration:**\n- **Clock Source:** The ADC clock is prescaled to **1/12 of the PLL clock**, resulting in a **6 MHz clock** fed to the ADC.\n- **Interrupts and DMA:**\n  - Both the ADC interrupt and its associated DMA interrupt are disabled (We don't care since we read when we want).\n  - The DMA is configured as a **half-word-to-half-word transfer** in circular mode with low priority.\n- **Channel Scanning:**\n  - The ADC is set to **scan mode** to read multiple channels in sequence.\n  - It is **software-triggered** and, once started, continuously reads channels in a loop, storing the results in a dedicated buffer within the firmware's Board module.\n\n**Configured Channels:**\n1. **Supply Voltage (5V) Sensing:**\n   - **Pin:** PC2\n   - **Channel:** ADC1 Channel 8\n   - **Rank:** 1\n   - **Sampling Time:** 601.5 cycles\n\n2. **PCB Temperature Sensing:**\n   - **Pin:** PA2\n   - **Channel:** ADC1 Channel 3\n   - **Rank:** 2\n   - **Sampling Time:** 601.5 cycles\n\n3. **Internal Processor Temperature Sensing:**\n   - **Channel:** ADC1 Temperature Sensor channel\n   - **Rank:** 3\n   - **Sampling Time:** 601.5 cycles\n\n---\n\n##### ADC4\n\n\u003e This one is the main ADC used to receive echo signals from the sonar. It operates in a slave mode with 8 bit precision for fast readings triggered by **TIM1** and is configured as follows:\n\n- **Clock Source:** The ADC clock is fed with PLL clock resulting in a **72 MHz clock**.\n- **Interrupts and DMA:**\n  - The ADC interrupt is disabled. DMA Interrupt is enabled but its not so important only used as fallback.\n  - The DMA is configured as a **half-word-to-byte transfer** in normal mode with low priority.\n- **Channel Scanning:**\n  - No channel scanning is used. The ADC is configured to read only one channel.\n  - It is triggered by **TIM1** and reads the echo signal from the sonar aat fixed intervals by N repetitions set in **TIM1** repetition counter.\n\n**Configured Channels:**\n1. **Echo Return Signal:**\n   - **Pin:** PB15\n   - **Channel:** ADC4 Channel 5\n   - **Rank:** 1\n   - **Sampling Time:** Dynamically adjusted by firmware, ranging from 7.5 to 61.5 cycles.\n\n---\n\n##### OPAMPs\n\nThe operational amplifiers (OPAMPs) have some common configurations:\n  - User trimming is enabled.\n  - Self-calibration is enabled.\n\n---\n\n- **OPAMP2 and OPAMP3:**\n  - Configured in **PGA (Programmable Gain Amplifier)** mode (not connected mode).\n  - Default gain is set to a maximum of **16**, but this is dynamically adjusted to optimize signal quality.\n  - As these OPAMPs are connected to the external analog sector, all associated pins are set to **analog mode**.\n\n---\n\n- **OPAMP4:**\n  - Configured in **standalone mode**.\n  - All associated pins are set to **analog mode**.\n  - Works in conjunction with the internal **DAC** to adjust the bias (offset) of the received signal since PGA OPAMPs introduces a lot of offset.\n\n##### DAC\n\n\u003e The internal DAC is used to adjust the bias (offset) of the received signal. Ideally the received signal should be centered around the mid range of the ADC, but due to mainly the **PGA** offsets introduced when changing the gain, the signal is not centered. The DAC is used to adjust this offset.\n\nConfiguration:\n- **OUT1 (PA4)** is configured to be used, it is connected to the **OPAMP4**.\n- **Output buffer**: disabled.\n- **Trigger Source:** None.\n\n### Dependencies\n\nBefore building the firmware, ensure that the necessary dependencies are installed:\n\n1. **Arm GNU Toolchain**\n   - The firmware is compiled using `arm-none-eabi-gcc`\n   - It can be installed from [Arm Developer](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain)\n\n1. **Ping Protocol**\n   - The sonar [communicates using the open-source Ping Protocol](#communication-and-interfacing), which enables structured message exchanges between the sonar and external systems\n   - For implementation, the sonar utilizes [ping-cpp](https://github.com/bluerobotics/ping-cpp), a C++ library that provides a structured interface for communicating with devices following the Ping Protocol\n   - This library facilitates message parsing, serialization, and device interaction\n\n1. **Boost CMake**\n   - Boost libraries are required for building the **ping-cpp** submodule\n   - You can install it using your package manager or download it from the [Boost website](https://www.boost.org/)\n\n### Building the firmware\n\nThe sonar firmware is developed using [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) for peripheral configuration, and can be imported into [STM32CubeIDE](https://www.st.com/en/development-tools/stm32cubeide.html) if needed.\n\nHowever, the primary method of compilation is [CMake](https://cmake.org/), which provides flexibility and ensures compatibility with various development environments.\n\nFollow these steps to build the firmware:\n\n```sh\ngit submodule update --init --recursive\ncd firmware\ncmake -B build\ncmake --build build --config Release --parallel\n```\n\nThis process generates the firmware binary, which can be flashed to the STM32 microcontroller.\n\n### Flashing the device\n\n#### Directly, via the command-line\n\nEntering the bootloader mode is essential for reflashing the sonar via the UART1 interface connected to the host computer. To enter bootloader mode, the `BOOT0` pin on the MCU must be pulled high, and the sonar must be reset.\n\nThis can be achieved as follows:\n1. **Manual Method:**\n   - Press the BOOT button on the sonar.\n   - Cut and restore power to the sonar while keeping the BOOT button pressed.\n   - Release the BOOT button after power is restored.\n\n2. **Automated Method:**\n   - Set the `BOOT_CHARGE_PIN` (`PB7`) high.\n   - Allow the independent watchdog timer to reset the sonar after a brief delay.\n\nThese methods ensure the device transitions into bootloader mode, enabling firmware updates.\n\nIf using the UART interface, you can use the **stm32flash** tool to flash the firmware. For example:\n\n```sh\nstm32flash -v -g 0x0 -b 115200 -w build/Release/ping-firmware-oss.hex \u003cyour device port\u003e\n```\n\nIt's also possible to flash the firmware via CMake to put the device in **bootloader mode**:\n\n```sh\ncmake -B build -DFLASH_DEVICE=/dev/ttyUSB0 \u0026\u0026 cmake --build build --config Release --parallel --target flash\n```\n\nMake sure to have the device in bootloader mode before flashing the firmware and that `\u003cyour device port\u003e` is changed to the correct port for the device, by example in a linux environment it could be `/dev/ttyUSB0`.\n\n#### Using Ping Viewer\nFirmware options that support the **Automated Method** can also be flashed using the [Ping Viewer](https://docs.bluerobotics.com/ping-viewer/firmware-update/#manual-firmware-update) software, if you prefer a digital interface, and to reduce the tools you need to install. Check more details in the [Firmware Update](https://docs.bluerobotics.com/ping-viewer/firmware-update/) documentation page.\n\n\n## Project history\n\nFor those interested in understanding how this project came to be, and how it has developed over time, here is a brief overview of its development so far:\n\n1. Activation - \"sonar is cool\", with clear desire in the marine robotics community to be able to play with and test different sonar configurations and algorithms\n1. Inspiration - affordable hardware with open communication protocols and established capabilities for basic applications is enticing as a starting point\n1. Investigation - Ping Sonar selected as a reverse engineering target, starting from evaluation of chip types and component values\n1. Exploration - PCB connections back-traced to create a high level schematic of a viable reference hardware\n1. Perspiration - schematic + chip datasheets used to create initial firmware\n1. Validation - Ping Protocol implemented for testing, and to ensure validity of reverse-engineering\n1. Communication - project licensed and shared openly, to allow the community to explore and contribute\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluerobotics%2Fping-firmware-oss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluerobotics%2Fping-firmware-oss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluerobotics%2Fping-firmware-oss/lists"}