Merge pull request #11 from pulp-bio/dev

WULPUS Release v1.1.0

CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All main changes to this project will be documented in this file.
+For the detailed description, please explore nested folders and corresponding CHANGELOG.md files (e.g. for PCB projects or firmware). 
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.1.0] - 2024-02-21
+
+### Added
+
+- WULPUS User Manual Rev 1 (`docs/wulpus_user_manual.pdf`)
+- MSP430 firmware (located at `fw/msp430`)
+- WULPUS programmer PCBs' design files (located at `hw/wulpus_programmer_pcbs`).
+- Generated production files (Assembly drawings, BOM, Gerber files, Drill files, Pick&Place files) for all the PCBs.
+- Added the dedicated GUIs to configure the excitation/receive and measurement settings.
+- Added example configurations and data.
+
+### Fixed
+
+- BLE Package loss by implementing buffering on the nRF52 MCU.
+- Multiple GUI bugs.
+
+### Changed
+
+- Updated the design of the acquisition and high-voltage PCBs
+- Improved the schematics of the PCB projects to simplify the outsourced assembly.
+- Improved the main WULPUS GUI and an example script.
+
+### Removed
+
+- Removed `./sw/docs` folder with the old GUI guide. The information about the GUI is now available in the WULPUS user manual.

README.md

@@ -15,7 +15,7 @@ The probe has the following features:
 - **30.8 dB** Programable-Gain Amplifier + **10 dB** Operational Amplifier
 - **Bluetooth Low Energy** (BLE) wireless link (320 kbps throughput)
 - Up to **50 acquisitions per-second** (APS) (400 samples per acquisition, raw data streaming mode)
-- **Compactness** (46 x25 mm footprint)
+- **Compactness and light weight** (46 x 25 mm footprint, 9 g)
 - **Ultra-Low Power** consumption of **22 mW** (raw data streaming mode, 50 APS)
 
 # WULPUS system diagram
@@ -34,18 +34,25 @@ This repository has the following folders:
 - `fw`, containing the firmware source code, namely:
     - source code for the nRF52832 MCU of the WULPUS probe, located at `fw/nrf52/ble_peripheral/US_probe_nRF52_firmware`
     - source code for the nRF52840 USB dongle, located at `fw/nrf52/peripheral/US_probe_dongle_firmware`
-    - source code for the MSP430 ultrasound MCU (will be added in the next release under the `fw/msp430` folder)
+    - source code for the MSP430 ultrasound MCU, located at `fw/msp430`
 - `sw`, containing the Python code for the WULPUS Graphical User Interface
 
 - `hw`, containing the Altium designer source files and pdf schematics for 
     - WULPUS Acquisition PCB (located at `hw/wulpus_acquisition_pcb`)
     - WULPUS High-Voltage PCB (located at `hw/wulpus_hv_pcb`)
+    - WULPUS Programmer PCBs (located at `hw/wulpus_programmer_pcbs`)
 
-- `docs`, containing the project documentation (e.g., images of the device, user guide, ...)
+- `docs`, containing the project documentation (e.g., images of the device, user manual, ...)
+
+# Documentation 
+
+The comprehensive [WULPUS User Manual](docs/wulpus_user_manual.pdf) can be found in the `docs/` folder. It covers everything about WULPUS, from assembly instructions to example measurements and troubleshooting, making the platform user-friendly for everyone, regardless of technical expertise.
 
 # How to reproduce?
 
-To build your own instance of WULPUS, the following steps should be completed:
+Please find the detailed instructions in chapter 2 of the [WULPUS User Manual](docs/wulpus_user_manual.pdf).
+
+In a nutshell, to build your own instance of WULPUS, the following steps should be completed:
 1. *PCBs manufacturing and assembly*<br>
    You can find the design files (Altium source files, schematics, bills of materials) under the `hw` folder.
 2. *Flashing MSP430 firmware*<br>
@@ -57,6 +64,9 @@ To build your own instance of WULPUS, the following steps should be completed:
 
 # Usage
 
+Please refer to chapter 3 of the [WULPUS User Manual](docs/wulpus_user_manual.pdf) for detailed information.
+
+Starting a measurement with WULPUS can be accomplished in three simple steps:
 - Power up the probe, either from the micro-USB connector or from the battery connector
 - Connect the USB dongle to the host PC
 - Activate the Python environent, launch the Jupyter notebook located in `sw` folder, and follow the instructions in the notebook
@@ -74,18 +84,26 @@ If you would like to reference the project, please cite the following paper:
   organization={IEEE}
 }
 ```
+# Works that use WULPUS
 
-## Authors
+[1] Vostrikov, Sergei, et al. "Hand gesture recognition via wearable ultra-low power ultrasound and gradient-boosted tree classifiers." 2023 IEEE International Ultrasonics Symposium (IUS). IEEE, 2023.
+
+[2] Vostrikov, Sergei, Luca Benini, and Andrea Cossettini. "Complete Cardiorespiratory Monitoring via Wearable Ultra Low Power Ultrasound." 2023 IEEE International Ultrasonics Symposium (IUS). IEEE, 2023.
+
+[3] Frey, Sebastian, et al. "A wearable ultra-low-power semg-triggered ultrasound system for long-term muscle activity monitoring." 2023 IEEE International Ultrasonics Symposium (IUS). IEEE, 2023.
+
+# Authors
 
 The WULPUS system was developed at the [Integrated Systems Laboratory (IIS)](https://iis.ee.ethz.ch/) at ETH Zurich by:
-- [Sergei Vostrikov](https://scholar.google.com/citations?user=a0KNUooAAAAJ&hl=en) (Firmware, Software, Open-Sourcing)
-- [Sebastian Frey](https://www.linkedin.com/in/sebastian-frey-8b576b194/) (Firmware, PCB design)
+- [Sergei Vostrikov](https://scholar.google.com/citations?user=a0KNUooAAAAJ&hl=en) (Firmware, Software, Open-Sourcing, Documentation)
+- [Sebastian Frey](https://scholar.google.com/citations?user=7jhiqz4AAAAJ&hl=en) (Firmware, PCB design, Documentation)
 - [Luca Benini](https://scholar.google.com/citations?hl=en&user=8riq3sYAAAAJ) (Supervision, Conceptualization)
 - [Andrea Cossettini](https://scholar.google.com/citations?user=d8O91jIAAAAJ&hl=en) (Supervision, Project administration)
 
-# References
+Thanks to all the people who contributed to the WULPUS platform:
+- [Cédric Hirschi](https://www.linkedin.com/in/c%C3%A9dric-cyril-hirschi-09624021b/) (GUI improvements, Documentation)
+- [William Bruderer](https://www.linkedin.com/in/william-bruderer-59ba9b26b/) (Documentation)
 
-[1] - Frey, Sebastian, Sergei Vostrikov, Luca Benini, and Andrea Cossettini. "WULPUS: a Wearable Ultra Low-Power Ultrasound probe for multi-day monitoring of carotid artery and muscle activity." In 2022 IEEE International Ultrasonics Symposium (IUS), pp. 1-4. IEEE, 2022.
 
 # License
 The following files are released under Apache License 2.0 (`Apache-2.0`) (see `sw/LICENSE`):
@@ -102,4 +120,7 @@ License (`CC-BY-4.0`) (see `docs/images/LICENSE`):
 - `docs/images/`
 
 The `fw/msp430/` and `fw/nrf52/` directories contain third-party sources that come with their own
-licenses. See the respective folders and source files for the licenses used.
+licenses. See the respective folders and source files for the licenses used.
+
+## Limitation of Liability
+In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.

docs/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.1.0] - 2024-02-21
+
+### Added
+
+- WULPUS user manual Rev 1.
+- Added the new photos of the WULPUS PCBs v1.1 folder into the dedicated subfolder (`./images/v1_1`).
+
+### Fixed
+
+### Changed
+
+- Moved `./images` folder into the dedicated subfolder (`./images/v1_0`)
+
+### Removed

docs/README.md

@@ -1,2 +1,2 @@
 # Folder for the documentation
-User Guide will be added in the next releases
+In this folder you can find the official wulpus user manual and the photos of the system. 

docs/images/README.md

@@ -1,8 +1,11 @@
 # Images
 
 ## Authors
-- [Frank K. Gürkaynak, ETH Zurich](https://iis-people.ee.ethz.ch/~kgf/) (*.jpg files)
-- [Sergei Vostrikov, ETH Zurich](https://scholar.google.com/citations?user=a0KNUooAAAAJ&hl=en) (*.png files)
+- [Frank K. Gürkaynak, ETH Zurich](https://iis-people.ee.ethz.ch/~kgf/) (*.jpg files in `./v1_0`)
+- [Sergei Vostrikov, ETH Zurich](https://scholar.google.com/citations?user=a0KNUooAAAAJ&hl=en) (*.png files and the photos in `./v1_1`)
+
+# Acknoledgment
+We would like to recognize the help of [Victor Kartsch, ETH Zurich](https://scholar.google.it/citations?user=0LY6szsAAAAJ&hl=it) in preparing the media content for WULPUS v1.1 release.
 
 # License
 The images are licensed under a [Creative Commons Attribution 4.0 International

fw/msp430/README.md

@@ -1 +1,11 @@
-# Folder for the MSU 430 US sensing MCU firmware
+# WULPUS source files for MSP430 Ultrasound MCU firmware project
+This directory contains the source firmware files for 
+- MSP430FR5043 Ultrasound MCU (`fw/msp430/wulpus_msp430_firmware`) mounted on the WULPUS acquisition PCB 
+
+# How to get started?
+
+1. Follow the file `fw/msp430/how_to_setup_msp_430_toolchain_and_flash.md` to install the toolchain and SDK
+2. Follow the same file to flash the MSP430 MCU on the WULPUS acquisition PCB.
+
+# License
+The files in the `hw/nRF52/wulpus_msp430_firmware` directory contains third-party sources that come with their own licenses (primarily BSD and Apache 2.0 License). See the respective folders and source files' headers for the licenses used.

fw/msp430/how_to_setup_msp_430_toolchain_and_flash.md

@@ -0,0 +1,20 @@
+# Setup of the TI MSP430 toolchain
+
+### TI Code Composer Studio (CCS) (V11.0.0.00012):
+`https://www.ti.com/tool/CCSTUDIO#downloads`
+- Download the single file installer, extract it and run the ccs_setup_11.0.0.00012 file
+- Choose custom installation
+- In "Select Components", select MSP430 ultra-low power MCUs and finish the installation
+
+# Flash the firmware to the MSP430
+
+### To flash the MSP430 firmware:
+Open the project in Code Composer Studio (CCS)
+- Open CCS, set the workspace to default value
+- Select File > Open Projects from File System...
+- Select Directory, set it to `/fw/msp430/wulpus_msp430_firmware` and then click Finish
+- Select Project > Build Configurations > Set Active > Debug
+- Build the project
+- Connect the MSP FET programmer to the US probe using the 8-pin Molex connector according to the diagram in the User Guide.
+- Power the US probe with a battery or USB (Set the jumper P2 accordingly)
+- Flash the code: Click on the Flash icon (if necessary select a binary file called `wulpus_msp430_firmware.out`)

fw/msp430/wulpus_msp430_firmware/.ccsproject

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<?ccsproject version="1.0"?>
+<projectOptions>
+	<ccsVersion value="11.0.0"/>
+	<deviceVariant value="MSP430FR5043"/>
+	<deviceFamily value="MSP430"/>
+	<deviceEndianness value="little"/>
+	<codegenToolVersion value="21.6.0.LTS"/>
+	<isElfFormat value="true"/>
+	<connection value="common/targetdb/connections/TIMSP430-USB.xml"/>
+	<linkerCommandFile value="lnk_msp430fr5043.cmd"/>
+	<rts value="libc.a"/>
+	<createSlaveProjects value=""/>
+	<templateProperties value="id=com.ti.common.project.core.emptyProjectWithMainTemplate_msp430"/>
+	<filesToOpen value="main.c"/>
+	<isTargetManual value="false"/>
+</projectOptions>