dsap Flashing Instructions (development)¶

These development instructions include help with commands, implementation notes, examples, and troubleshooting detail for developers and maintainers. For the operator production workflow, use dsap Flashing Instructions (production).

Purpose¶

Use these instructions on an Assembly Laptop to:

1. Flash firmware to the MSP430 MCU.
2. Optionally create a BioT device object and certificate bundle.
3. Load the device certificate bundle into the SARA module.
4. Calculate the gel sensing threshold and set final device parameters.

Prerequisites¶

Before starting, confirm the following:

1. You have already completed the dsap Setup Instructions on this Assembly Laptop.
2. The MSP-FET or other supported TI flash tool is connected to the target hardware.
3. You have the certificate bundle .zip file for the device.
4. You know which firmware tag to flash, for example 1.0.1, v1.0.1, or v1.0.1-beta.1, or you have been told to use latest.
5. You have the Sonogen Transducer Voltage Characteristics reference document with Envelope Voltage values by transducer serial number.
6. If you plan to create BioT device objects from dsap, the optional BioT API setup in the setup instructions is complete.

Flashing Module Switches¶

Use these Sonogen Flashing Module switches for each operation:

1. Flash the MCU Firmware with dsap mcu¶

Use dsap mcu from the Assembly Laptop to fetch the requested firmware bundle and flash it with the TI flasher utility.

1.1 Prepare the Hardware¶

1. Boot the Sonogen Assembly Laptop into Windows.
2. Connect the MSP-FET to the Assembly Laptop.
3. Connect the 14-pin connector from the MSP-FET to the Sonogen Flashing Module.
4. Connect the Sonogen Flashing Module to the assembled device with the cable oriented as shown.

1.2 Find the MSP-FET COM Port¶

By default, dsap mcu assumes:

1. The FET debugger is on COM3.
2. The flasher executable is under C:\TI in a versioned MSPFlasher_* or MSP430Flasher_* installation directory. If multiple versions are installed, dsap uses the newest one it finds.

Before flashing, use MSP430 Flasher to discover the COM port assigned to the MSP-FET. Open Windows PowerShell and run:

irm https://docs.sonogenmed.com/assets/downloads/check-msp430-fet.ps1 | iex

The helper finds the newest standard TI installation and runs the executable by its full path, so it works from any directory without a Windows Path change. If it cannot find the utility, run its actual path with & "C:\Path\To\MSP430Flasher.exe" -n NO_TARGET -i DETECT.

The command lists connected FET debuggers, checks FET firmware compatibility, and may prompt you to select one. Example output for a FET with up-to-date firmware:

* -----/|------------------------------------------------------------- *
*     / |__                                                            *
*    /_   /   MSP Flasher v1.3.20                                      *
*      | /                                                             *
* -----|/------------------------------------------------------------- *
*
* Evaluating triggers...done
* Executing FET detection sweep:
 - 1: MSP-FET @ COM7
 - Select FET number: 1
* Initializing interface @ COM7...done
* Checking firmware compatibility:
* FET firmware is up to date.
*
* ----------------------------------------------------------------------
* Driver      : closed (No error)
* ----------------------------------------------------------------------
*/

If prompted, enter the listed FET number. In the example above, enter 1 and use --port 7 with dsap mcu. If multiple FETs are connected, MSP430 Flasher may list multiple numbered choices. Select the FET connected to the target hardware.

1.3 Run dsap mcu¶

Run this command, replacing <TAG> with the firmware tag and <PORT> with the MSP-FET COM port number:

dsap mcu <TAG> --port <PORT>

Example:

dsap mcu v1.0.1 --port 7

The <TAG> value can be a release tag such as v1.0.1 or 1.0.1, a prerelease tag such as v1.0.1-beta.1, or latest when you have been told to use the current default production firmware. If you omit the leading v, dsap still flashes the same firmware and prints the canonical v... tag in its status output.

Normally no --flasher option is needed. Use --flasher "C:\Path\To\MSP430Flasher.exe" only if MSP430 Flasher is not under the standard C:\TI\MSPFlasher_* or C:\TI\MSP430Flasher_* location.

For developer debug builds that have not been staged in dsap-fw, pass the local firmware file with --local-fw. The firmware tag is still required and is printed as the test identifier when flashing succeeds:

dsap mcu v1.0.1-local --local-fw "C:\Path\To\MSP430_firmware.txt" --port 7

--local-fw skips the remote firmware repository fetch and manifest checksum verification. Use it only for local development and debugging, not for production traveler-driven flashing.

1.4 What dsap mcu Does¶

When you run dsap mcu, it:

1. Fetches the firmware bundle from the Sonogen firmware repository at the selected tag, unless --local-fw points to a local debug build.
2. Verifies the firmware bundle checksum for repository-sourced firmware.
3. Invokes MSP430Flasher.exe.
4. Uses the selected COM port, erase mode, verification, and power control settings required by the current implementation.

1.5 Expected On-Screen Output¶

You should see status lines similar to:

  Firmware tag: v1.0.1 ✅
      Flashing the MCU ✅
Device flashed with firmware version: v1.0.1

If the requested tag does not exist, dsap reports a firmware build error and notes that the tag may not exist.

If the flasher utility is missing, you should expect:

      Flashing the MCU ❌
MSP430 Flasher utility not found. Check installation.

Optional: Create a BioT Device and Certificate Bundle¶

Use dsap serial --create when you want dsap to create the BioT device object and download the production certificate bundle. Developers who already have a test certificate bundle, or who are testing only MCU flashing or local serial-number behavior, may skip bundle creation.

Example:

dsap serial --create

When --create is used, dsap authenticates to BioT, creates the device with the generated serial number as the BioT Unique ID using the configured service user, refreshes the stored BioT administrator token, downloads the production certificate bundle to C:\Users\<USER>\dsap\certificates\<serial-number>.zip, and prints the full path. The generated ZIP includes connectionDetails.txt with the Sonogen BioT IoT endpoint and a client ID derived from the serial number. If --create is omitted, dsap serial keeps its existing local-only behavior.

2. Upload Device Certificates with dsap sara¶

Use dsap sara to configure the SARA module and upload the device certificate bundle.

2.1 Certificate Bundle Requirements¶

The input must be a .zip file. A certificate bundle generated by dsap serial --create includes files whose names end with:

1. caCertificate.txt
2. certificate.txt
3. privateKey.txt
4. connectionDetails.txt

2.2 Prepare the Hardware¶

Disconnect the MSP-FET. Connect a USB data cable from the Assembly Laptop to the USB-C port on the Sonogen Flashing Module.

2.3 Find the USB Serial COM Port¶

1. Open Device Manager on the Assembly Laptop.
2. Expand Ports (COM & LPT).
3. Find the COM port assigned to the USB serial connection.
4. Note only the number for use with dsap sara and dsap params. For example, note 7 for COM7.

2.4 Run the Command¶

Example with defaults:

dsap sara "C:\Users\<USER>\dsap\certificates\<serial-number>.zip"

Example with another COM port and debug logging:

dsap sara "C:\Users\<USER>\dsap\certificates\<serial-number>.zip" --port 7 --debug

2.5 What dsap sara Does¶

dsap sara performs these stages:

1. Stages the certificates into the internal C:\Users\<USER>\dsap\certificate_staging area.
2. Opens the requested serial port, default COM3.
3. Connects to the SARA module.
4. Purges any existing rootCA, clientCert, and clientKey certificates already on the module.
5. Uploads the new certificate set.
6. Closes the serial connection.

The command retries module connection and certificate purge operations up to three times before failing.

2.6 Expected On-Screen Output¶

You should see status lines similar to:

     Staging the certificates ✅
      Connecting to port COM3 ✅
Connecting to the SARA module ✅
 Purging the old certificates ✅
 Loading the new certificates ✅
Closing the serial connection ✅

SARA configuration successful.

3. Configure Final Parameters with dsap params --gelset¶

Run dsap params --gelset after certificate upload with dsap sara. Developers may use this guided workflow to streamline device provisioning for production or testing. It writes setup parameter values needed for gel sensing measurement, captures firmware Median readings from the dry and gel test rig positions, calculates the final Gel Sensing Threshold, and writes final parameter values to the device.

3.1 Run the Guided Setup Command¶

Use the same USB serial COM port number found in section 2.3 and run dsap params --gelset.

Example with defaults:

dsap params --gelset

Example with another port:

dsap params --gelset --port 7

3.2 Parameter Prompts¶

dsap params --gelset reuses the same Client ID, Gel Sensing Threshold, and Envelope Voltage prompts as plain dsap params.

Use these values during setup:

1. Client ID from the recent certificate bundle, unless a different non-empty value is required for the test.
2. Accept the default Gel Sensing Threshold of 50m unless the traveler or work order specifies a different value. This value is written before measurement so the device can report Median readings. It is overwritten later by the calculated final value.
3. Envelope Voltage from the Sonogen Transducer Voltage Characteristics reference document for the device transducer serial number.

Envelope Voltage is a traveler record. If the value is 0, dsap requires sham-device confirmation before writing setup and final parameters.

3.3 Measurement Behavior¶

After setup values are written, dsap params --gelset guides the operator through the dry and gel measurement sequence. The instructions in the command own the detailed reset, magnet, gel application, and test rig actions.

For each measurement phase, the command opens the selected USB serial port at 57600 baud before the operator starts the device. The dry and gel phases both start the device by placing a magnet temporarily near the Hall sensor. After the turn-on prompt appears, the command immediately waits up to 120 seconds for the first usable firmware line in this format while the operator places the magnet near the Hall sensor:

Median: 4455021

The same parsing path is used for the dry and gel positions. The command ignores unrelated firmware output while waiting for Median, including startup banners, built-in test output, repeated Received Signal Energy lines, SD-card session messages, idle-mode messages, malformed replacement characters from serial decoding, and Gel Sensing : Fail.

After each capture attempt, the command prints whether automatic serial capture succeeded:

dry reading captured: ✅
gel reading captured: ✅

If automatic capture fails, the command prints ❌ for that reading and prompts for manual entry.

The dry and gel readings are displayed later in the final pre-write summary. They are informational only. The final parameter values in that summary are traveler records.

3.4 Threshold Calculation¶

After both readings are captured, dsap params --gelset calculates:

round_nearest((dry_reading + gel_reading) / 2)

The implementation uses explicit half-up behavior for .5 values. It rejects missing readings and equal readings. It does not require a specific ordering between dry_reading and gel_reading.

Record the calculated final Gel Sensing Threshold on the traveler. After calculation, dsap params --gelset displays the dry reading, gel reading, Client ID, Envelope Voltage, and calculated Gel Sensing Threshold. The Client ID, Envelope Voltage, and calculated Gel Sensing Threshold are the final values to be written to the device and are traveler records. The command then prompts for the parameter-setting switch action and writes those final values to the device.

4. Manual Parameter Writes with dsap params¶

Plain dsap params remains available for development and troubleshooting when you need to write known parameter values directly. For streamlined device provisioning, including developer test devices, use dsap params --gelset instead. Do not run plain dsap params as a separate production step after successful dsap params --gelset unless a developer or station owner explicitly directs a manual parameter rewrite.

4.1 Run a Manual Parameter Write¶

Use the same USB serial COM port number found in section 2.3.

Example with defaults:

dsap params

Example with another port and debug logging:

dsap params --port 7 --debug

4.2 Client ID Prompt Behavior¶

If a staged certificate bundle is present and includes connection details, dsap params first offers the client ID from that bundle.

Example:

Client ID from certificate bundle: ABC123456
Use this Client ID (y/n)?

If you answer n, dsap prompts you to enter a client ID manually.

Manual client ID rule:

1. The value must not be empty.
2. Maximum length is 32 characters.

Example prompt:

+--------------------------------------------------------------------+
| Enter the Client ID. This must be a non-empty value that is no     |
| more than 32 characters long.                                      |
+--------------------------------------------------------------------+
Client ID:

4.3 Gel Sensing Threshold Rules¶

The default Gel Sensing Threshold is 50m. Accept it unless the traveler or work order specifies a different value. Manual values must be positive integers; for a directed manual rewrite after a --gelset run, enter the value specified by the traveler or work order.

dsap accepts fuzzy formats such as:

1. 1
2. 750000
3. 750,000
4. 750_000
5. 750k
6. 0.75M
7. .75m
8. 2M

Example prompt:

+--------------------------------------------------------------------+
| The default Gel Sensing Threshold is 50m. Accept it unless the     |
| traveler or work order specifies a different threshold. Manual     |
| values must be positive integers. Fuzzy inputs are accepted.       |
+--------------------------------------------------------------------+
Gel Sensing Threshold: 50m
Use this Gel Sensing Threshold (y/n)?

If the value cannot be parsed or is not greater than zero, dsap prints:

Invalid Gel Sensing Threshold.

4.4 Envelope Voltage Rules¶

The envelope voltage must be an integer from 0 through 63, inclusive. Enter the Envelope Voltage from the Sonogen Transducer Voltage Characteristics reference document. A value of 0 creates a sham device.

Example prompt:

+--------------------------------------------------------------------+
| Enter the Envelope Voltage. This must be an integer in the range   |
| [0, 63] (inclusive). A value of 0 indicates a sham device.         |
+--------------------------------------------------------------------+
Envelope Voltage:

If you enter 0, dsap displays a sham-device warning and requires confirmation:

By setting the envelope voltage to zero you are creating a "sham"
device. This is a test device that provides no therapeutic signal.

Proceed (y/n)?

If you answer n, dsap exits without making changes.

4.5 Expected On-Screen Output¶

After values are collected, dsap prints:

Updating device parameters...

Then it runs the device update stages:

            Opening port COM3 ✅
            Setting Client ID ✅
Setting Gel Sensing Threshold ✅
     Setting Envelope Voltage ✅
            Closing port COM3 ✅

Do not disconnect the hardware until the port close stage completes.

5. Verify Gel-Pass and Dry-Fail Behavior¶

After dsap params --gelset writes the final parameters, follow its guided prompts:

1. Keep the device connected to the flash module and in contact with the phantom tissue. Start a treatment session by temporarily placing a magnet near the Hall sensor.
2. Verify that the blue therapy lights turn on and begin flashing.
3. Press and hold the reset button on the flash module for five seconds to stop the device.
4. Wipe gel thoroughly from the transducer face. Place the device in the dry position on the test rig again, while leaving it connected to the flash module.
5. Turn the device on by temporarily placing a magnet near the Hall sensor.
6. Verify that the red failure light turns on.
7. Press and hold the reset button on the flash module for five seconds to stop the device.
8. Remove the device from the dry position, disconnect it from the flash module, and report that parameter setting is complete.

6. Troubleshooting Notes¶

1. If dsap mcu fails before flashing, verify the firmware tag and confirm the Assembly Laptop can access Sonogen's GitLab repository.
2. If dsap mcu reports that the MSP430 flash utility is not found, confirm MSP430 Flasher was installed from TI as a Windows Administrator, or rerun the command with --flasher.
3. If MSP430 Flasher is installed but Windows does not recognize the MSP-FET, install the standalone TI MSP430 FET Drivers package as a Windows Administrator. Then unplug and reconnect the MSP-FET and confirm the COM port in Windows Device Manager.
4. If dsap sara, dsap params --gelset, or dsap params cannot open the port or connect to the device, confirm the MSP-FET is disconnected, a USB data cable is connected from the Assembly Laptop to the USB-C port on the Sonogen Flashing Module, and the correct USB serial COM port number is used. dsap expects only the number, for example --port 7, not --port COM7.
5. If dsap sara fails while staging certificates, verify that the input is a valid .zip file and that the required certificate files are present.
6. If dsap params prompts with the wrong client ID, answer n and enter the correct value manually.
7. If dsap params --gelset cannot capture a usable Median line, it prompts for manual entry. Confirm the device was reset, the USB data cable is still connected, the correct COM port was selected, and the device was turned on for the active dry or gel phase.
8. If serial output contains malformed characters but still includes a readable Median: <integer> line, the command should parse the Median line and continue.
9. If dry_reading and gel_reading are equal, repeat the gel sensing setup. Equal readings are rejected because they do not establish a useful threshold.
10. If Gel Sensing : Fail appears after a captured Median line during dsap params --gelset, treat it as expected in the current test environment. The command should not fail for that text alone.
11. If final gel-pass or dry-fail verification fails, stop and review the selected Envelope Voltage, calculated Gel Sensing Threshold, final parameter values, transducer gel application, and test rig positioning before retesting.

References¶

1. dsap Setup Instructions
2. TI MSP430 Flasher tool page: https://www.ti.com/tool/MSP430-FLASHER
3. TI MSP430 Flasher user's guide: https://www.ti.com/document-viewer/lit/html/slau654
4. TI MSP430 FET Drivers page: https://software-dl.ti.com/msp430/msp430_public_sw/mcu/msp430/MSP430_FET_Drivers/latest/index_FDS.html