Skip to content

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. Set the 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. 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:

Operation Switch
MCU flashing U2
Certificate upload U3
Parameter setting U4

1. Flash the MCU Firmware with dsap mcu

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

1.1 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 in the MSP430 Flasher installation directory and run:

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.2 Run dsap mcu

Operator STOP: Before running dsap mcu, stop and set flashing module switches U2, U3, and U4 up. Do not run the command until all three switches are up.

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.

1.3 What dsap mcu Does

When you run dsap mcu, it:

  1. Clones the Sonogen firmware repository at the selected tag.
  2. Verifies the firmware bundle checksum.
  3. Invokes MSP430Flasher.exe.
  4. Uses the selected COM port, erase mode, verification, and power control settings required by the current implementation.

1.4 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 Run the Command

Operator STOP: Before running dsap sara, stop and flip certificate upload switch U3 down, press the reset button, then flip U3 back up. Do not run the command until U3 is back up.

Example with defaults:

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

Example with another COM port and verbose logging:

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

2.3 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.4 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. Set Device Parameters with dsap params

Run dsap params after the MCU has been flashed. This step writes the client ID, gel sensing threshold, and envelope voltage to the device.

3.1 Run the Command

Operator STOP: Before running dsap params, stop and flip parameter setting switch U4 down, press the reset button, then flip U4 back up. Do not run the command until U4 is back up.

Example with defaults:

dsap params

Example with another port and verbose logging:

dsap params --port 7 --verbose

3.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:

3.3 Gel Sensing Threshold Rules

The gel sensing threshold must be a positive integer greater than zero.

dsap accepts fuzzy formats such as:

  1. 1
  2. 500000
  3. 500,000
  4. 500_000
  5. 500k
  6. 0.5M
  7. .5m
  8. 2M

Example prompt:

+--------------------------------------------------------------------+
| Enter the Gel Sensing Threshold. This is a positive integer        |
| greater than zero. Fuzzy inputs are accepted.                      |
+--------------------------------------------------------------------+
Gel Sensing Threshold:

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

Invalid Gel Sensing Threshold.

3.4 Envelope Voltage Rules

The envelope voltage must be:

  1. 0, which creates a sham device, or
  2. an integer from 42 through 63, inclusive.

Example prompt:

+--------------------------------------------------------------------+
| Enter the Envelope Voltage. This must be 0 (indicating a sham      |
| device) or an integer in the range [42, 63] (inclusive).           |
+--------------------------------------------------------------------+
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.

3.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.

4. 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 serial-based commands fail, verify the correct COM port number. 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.

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