Skip to content

dsap Setup Instructions

Purpose

Use these instructions on an Assembly Laptop to install dsap, initialize its local provisioning data, and prepare the system for device flashing and provisioning.

Flashing and configuring devices using dsap is currently Windows-only. Maintenance and development of dsap require a Linux-like environment, such as macOS or Linux, and are not part of this procedure.

After you complete this setup, continue with the dsap Flashing Instructions (production).

Setup Overview

Before starting, confirm that you are working on an Assembly Laptop, that Windows PowerShell is available, and that you have permission to access Sonogen's private GitLab repositories.

This procedure will guide you through the following setup steps:

  1. Open Windows PowerShell, which must be used for this setup. Do not use PowerShell 7, pwsh, Windows Terminal's PowerShell 7 profile, or Windows PowerShell ISE for this procedure.
  2. Install or verify uv from Windows PowerShell.
  3. Install or verify Git from Windows PowerShell.
  4. Configure SSH access for Sonogen's private GitLab repositories.
  5. Install dsap.
  6. Install the Texas Instruments MSP430 Flasher utility and required TI MSP430 FET drivers as a Windows Administrator.
  7. Check the MSP-FET firmware version and update it if needed.
  8. Initialize dsap.
  9. Optionally configure BioT API access for device provisioning.

1. Open Windows PowerShell

Long commands and multi-line command blocks in this guide may be copied and pasted into Windows PowerShell. If Windows warns that the pasted text contains multiple lines, click Paste anyway. This guide uses multi-line commands intentionally so the pasted block waits for the final press of the Enter key before it runs.

From the Windows Start menu, search for exactly:

Windows PowerShell

Open the app named Windows PowerShell. Do not open PowerShell 7, pwsh, Windows Terminal's PowerShell 7 profile, or Windows PowerShell ISE for this procedure.

Confirm that the current shell is Windows PowerShell:

$PSVersionTable.PSEdition; `
$PSVersionTable.PSVersion; `
(Get-Process -Id $PID).Path

Expected results:

The major version should be 5, and you should see output similar to this:

Desktop

Major  Minor  Build   Revision
-----  -----  -----   --------
5      1      26100   8328
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe

PowerShell 7 is a separate shell that runs side-by-side with Windows PowerShell. It is launched as pwsh.exe and is not the validated shell for this setup procedure.

2. Install uv

Follow the official Astral uv installation instructions for Windows:

https://docs.astral.sh/uv/getting-started/installation/

The official page includes Windows installation methods such as the PowerShell installer and winget. If you want a quick reference, Astral currently documents:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

or:

winget install --id=astral-sh.uv -e

After installation, close your PowerShell window, open a new one, and confirm uv is available:

uv --version

Example:

uv 0.11.7

If uv is not recognized immediately after installation, close all PowerShell windows and open a new Windows PowerShell session before retrying uv --version.

3. Install Git for Windows

Follow the official Git for Windows installation page:

https://git-scm.com/install/windows

That page links to the currently maintained Windows installer and also documents a winget option:

winget install --id Git.Git -e --source winget

After installation, confirm Git is available:

git --version

Example:

git version 2.54.0.windows.1

If Git is not recognized immediately after installation, close all PowerShell windows and open a new Windows PowerShell session before retrying git --version.

4. Check for an Existing SSH Public Key

Valid SSH keys are required to install and run dsap. Providing your public SSH key to the Sonogen Development Team will allow you to install and run dsap commands without requiring a username and password.

Open Windows PowerShell and run:

Get-ChildItem "$env:USERPROFILE\.ssh\*.pub" -ErrorAction SilentlyContinue

If an existing public key file is listed, continue to the next step. If no public key file is listed, create a new ED25519 SSH key pair:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.ssh"; `
ssh-keygen -t ed25519 -C "Assembly Laptop" -f "$env:USERPROFILE\.ssh\id_ed25519" -N ""

The -N "" option creates the key without a passphrase so this step can run without an interactive passphrase prompt. NEVER EMAIL OR SHARE THE PRIVATE KEY FILE.

5. Send the Public SSH Key to the Sonogen Development Team

Open Windows PowerShell and copy the public key to the clipboard:

Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub" | Set-Clipboard

If you are using a different existing public key file, replace id_ed25519.pub with that file name. Email the copied public key to a member of the Sonogen Development Team.

Operator STOP: Stop here until you receive confirmation from the Sonogen Development Team that your public key has been added to GitLab. The installation of dsap cannot succeed until that access is in place.

Sonogen Development Team: Enable this public key as a read-only deploy key on both private GitLab repositories: sonogen/dsap and sonogen/dsap-fw. For GitLab deploy-key instructions, see https://docs.gitlab.com/user/project/deploy_keys/.

6. Verify GitLab SSH Access

After the Sonogen Development Team confirms that the public key has been added to GitLab, verify SSH access before installing dsap.

Open Windows PowerShell and run:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.ssh"; `
ssh -T git@gitlab.com

The first time you connect to GitLab, Windows may ask whether to trust the gitlab.com SSH host key. To verify the prompt before accepting, compare the displayed SHA256 fingerprint with GitLab's published SSH host key fingerprints:

https://docs.gitlab.com/user/gitlab_com/#ssh-host-keys-fingerprints

When you're ready to proceed, type:

yes

This records GitLab's host key in your SSH known_hosts file. After the host key is accepted, the command may print a GitLab welcome or authentication message. Continue to the next step after GitLab's host key has been trusted.

7. Install dsap

dsap is installed as a uv tool from Sonogen's private GitLab repository.

Open Windows PowerShell and run:

$env:UV_PYTHON_PREFERENCE="only-managed"; uv tool install --force --from git+ssh://git@gitlab.com/sonogen/dsap.git@latest dsap

If you later need to reinstall dsap or replace it with a beta or release candidate build, use the same uv tool install --force ... pattern with the requested source or version. If uv reports an authentication or clone failure, check with a member of the Sonogen Development Team.

After installation, confirm the CLI is available:

dsap -h

You should see output similar to:

usage: dsap [-h] [-v] {biot,init,mcu,mobile,params,sara,serial} ...

Device Setup and Provisioning (dsap). Flash firmware and provision Sonogen
devices.

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit

commands:
  For help with a command, run: dsap <command> -h

  {biot,init,mcu,mobile,params,sara,serial}

8. Install MSP430 Flasher and TI FET Drivers

dsap mcu uses the Texas Instruments MSP430 Flasher to write firmware to the MCU.

Before downloading the TI installers, make sure you have a free myTI account. If you do not already have one, register here:

https://www.ti.com/myti/nsdocs/register

Use the official TI sources:

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

8.1 Download Required Packages

From the TI tool page, download the Windows installer for MSP430 Flasher.

The MSP-FET also requires the TI low-level USB drivers package.

  1. If TI Code Composer Studio (CCS) is already installed on the Assembly Laptop, all the necessary drivers are in place. Proceed to step 8.2.
  2. If CCS is not installed, download the standalone TI MSP430 FET Drivers package from the TI MSP430 FET Drivers download page.

8.2 Install Required Packages

If MSP430 Flasher is installed as a regular user, the installer may not include required support files or enable logging support. Install MSP430 Flasher with Administrator elevation:

  1. Open File Explorer and go to the downloaded MSP430 Flasher installer.
  2. Right-click the installer and select Run as administrator.
  3. Approve the Windows User Account Control prompt.
  4. Complete the installation with the default TI options.

Install the standalone TI MSP430 FET Drivers package with Administrator elevation if CCS is not already installed:

  1. Open File Explorer and go to the downloaded FET drivers installer.
  2. Right-click the installer and select Run as administrator.
  3. Approve the Windows User Account Control prompt.
  4. Complete the installation with the default TI options.

dsap looks for the flasher executable under the standard TI installation root and automatically uses the newest installed MSP430 Flasher version that matches one of these patterns:

C:\TI\MSPFlasher_*\MSP430Flasher.exe
C:\TI\MSP430Flasher_*\MSP430Flasher.exe

If your TI installation places MSP430Flasher.exe somewhere else, you do not need to move it. Instead, pass the actual executable path to dsap mcu with --flasher.

Example:

dsap mcu v1.0.1 --flasher "C:\Path\To\MSP430Flasher.exe"

9. Check the MSP-FET Firmware Version

After MSP430 Flasher is installed, connect the MSP-FET to the Assembly Laptop with the USB programming cable. Open Windows PowerShell in the MSP430 Flasher installation directory and run:

MSP430Flasher.exe -n NO_TARGET -i DETECT

The command runs a FET detection sweep and checks whether the connected FET firmware is compatible with the installed MSP430 Flasher version. If prompted to select the FET, enter the listed FET number. In the example below, enter 1.

If the FET firmware needs an update, MSP430 Flasher displays output similar to this. When MSP430 Flasher asks whether to update the FET, enter y and press Enter.

* -----/|------------------------------------------------------------- *
*     / |__                                                            *
*    /_   /   MSP Flasher v1.3.20                                      *
*      | /                                                             *
* -----|/------------------------------------------------------------- *
*
* Evaluating triggers...done
* Executing FET detection sweep:
 - 1: MSP-FET @ COM7 (FW update needed)
 - Select FET number: 1
* Initializing interface @ COM7...done
* Checking firmware compatibility:
* The firmware of your FET is outdated.
- Would you like to update it? (Y/N): y

*********************************************************
*
*  Initializing Update Bootloader.
*  Programming new firmware:
*  |||||||||||||||||||||||||||||||||||||||||||||||||| 100%
*********************************************************
*
*  Initializing Update Bootloader.
*  Programming new firmware:
*  |||||||||||||||||||||||||||||||||||||||||||||||||| 100%
*  Update was successfully finished.
*
*********************************************************

*  Exit Update Bootlader and reboot firmware.
# Exit: 49
# ERROR: Could not find MSP-FET430UIF on specified COM port
*
* ----------------------------------------------------------------------
* Driver      : closed (No error)
* ----------------------------------------------------------------------
*/

The # Exit: 49 error at the end is expected while the FET reboots after the firmware update.

Run the same command again:

MSP430Flasher.exe -n NO_TARGET -i DETECT

When prompted to select the FET, enter the listed FET number again. In the example below, enter 1. Confirm that MSP430 Flasher reports that the FET firmware is up to date before continuing.

* -----/|------------------------------------------------------------- *
*     / |__                                                            *
*    /_   /   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)
* ----------------------------------------------------------------------
*/

10. Initialize dsap

After installing dsap, run this command to create the local provisioning environment:

dsap init

On a first-time setup, you should see output similar to:

 Creating certificate bundle directory ✅
Creating certificate staging directory ✅
        Creating mobile code directory ✅
              Creating label directory ✅
        Creating local config template ✅
          Initializing device baseline ✅

dsap init also creates C:\Users\<USER>\dsap\config.toml as a commented template for local, non-secret overrides. Uncomment any values on an Assembly Laptop that need to differ from the package defaults, such as BioT endpoints, mobile QR URLs, UID/model-number settings, or MSP430 Flasher discovery paths. Do not store credentials, bearer tokens, service-user secret keys, or refresh tokens in config.toml; BioT credential state belongs only in biot.json.

11. Optional BioT API Access

BioT API access is required for Assembly Laptops that will create BioT device objects and download certificate bundles with dsap serial --create. If this laptop will not provision devices in the BioT portal, skip this section.

Confirm you have BioT admin credentials for a user that can manage Service Users. dsap biot does not store the admin password, but it does store the admin refresh token needed for future certificate downloads.

Run the interactive BioT setup command:

dsap biot

The command prompts for:

  1. the BioT API endpoint;
  2. the BioT admin username;
  3. the BioT admin password;
  4. the BioT owner organization UUID for sonogen;
  5. the device template API name, for example sonogen_device, not the visual portal name;
  6. the service-user name;
  7. the BioT Tenant-Id header for organization-scoped requests.

Default values are presented in brackets. The default service-user name uses the current host name and local date/time in the format <host_name>-YYYYMMDD.HHMM. To accept defaults, press Enter. Once all steps are complete, dsap will be ready to create device objects in the BioT cloud.

If the command reports ACCESS_DENIED from the BioT User Management Service, confirm that the BioT admin account can manage service users, then retry with the BioT Tenant-Id header set to the organization UUID for the organization where the operation should run. If BioT reports that MFA or a password reset is required, complete that login requirement outside dsap and rerun the command. Contact the Sonogen Development Team if access is still denied.

Note: dsap biot creates the configuration file at C:\Users\<USER>\dsap\biot.json on Windows and ~/dsap/biot.json on macOS or Linux. Do not email, share, or commit this file; it contains sensitive service-user credentials and a BioT administrator refresh token that allow BioT device provisioning and certificate downloads. Protect this file as an administrator credential.

12. Continue to Flashing and Provisioning

After setup is complete, use the dsap Flashing Instructions (production) for the operator device workflow:

  1. Flash MCU firmware with dsap mcu.
  2. Generate the serial number and certificate bundle with dsap serial --create.
  3. Upload device certificates with dsap sara.
  4. Set final device parameters with dsap params.

For detailed command behavior and developer troubleshooting, see the dsap Flashing Instructions (development).

13. Troubleshooting Notes

  1. If dsap is not recognized, confirm the uv tool install --force ... step completed successfully and open a new Windows PowerShell session.
  2. If installation behaves unexpectedly, confirm UV_PYTHON_PREFERENCE=only-managed was included inline with the uv tool install --force command.
  3. If you are switching between stable, beta, or release candidate builds, rerun the install command with --force so uv replaces the previous dsap install cleanly.
  4. If dsap serial --create reports that the BioT config file is missing, complete the optional BioT API access section before provisioning devices in BioT.
  5. If dsap serial --create reports ACCESS_DENIED while downloading the certificate bundle, the stored BioT administrator credentials can authenticate but are not allowed to call the Device Certificate API. Confirm that dsap biot was run with a Manufacturer Admin account, and include the BioT traceId when contacting BioT support.
  6. If dsap init fails, verify that dsap was installed successfully on the Assembly Laptop before retrying.
  7. If MSP430 Flasher does not list the MSP-FET during the firmware check, verify that CCS is installed or that the standalone TI MSP430 FET Drivers package was installed as a Windows Administrator. Then unplug and reconnect the MSP-FET and confirm Windows Device Manager recognizes it.
  8. If the uv tool install command reports Host key verification failed, GitLab's SSH host key has not been trusted yet. Run ssh -T git@gitlab.com, verify the displayed fingerprint, accept it, and retry the uv tool install command.
  9. If GitLab host-key verification still fails, remove stale GitLab host entries and retry the SSH verification:
ssh-keygen -R gitlab.com; `
ssh-keygen -R "[gitlab.com]:22"; `
ssh -T git@gitlab.com
  1. If the error changes to Permission denied (publickey), GitLab's host key is trusted but SSH access is not working. Confirm the private key exists on the Assembly Laptop and the matching public key is enabled as a read-only deploy key on the required private GitLab repositories.
  2. If uv reports another SSH authentication error, confirm the Assembly Laptop public key is enabled as a read-only deploy key on both private GitLab repositories.
  3. If uv or Git works in one shell session but not another, the missing command may be caused by a stale PATH. Close all PowerShell windows, open a fresh Windows PowerShell session, and retry uv --version and git --version.
  4. Make sure you're using Windows PowerShell. Open the app named Windows PowerShell from the Start menu and run the shell verification commands from section 1.
  5. If uv still is not recognized, check whether the executable exists:
Test-Path "$HOME\.local\bin\uv.exe"; `
Get-Command uv -ErrorAction SilentlyContinue; `
[Environment]::GetEnvironmentVariable("Path", "User") -split ";"

If uv.exe exists but Get-Command uv prints nothing, confirm $HOME\.local\bin is present in the user Path, then open a new Windows PowerShell session. 15. If Git still is not recognized, check whether the executable exists:

Test-Path "$env:ProgramFiles\Git\cmd\git.exe"; `
Get-Command git -ErrorAction SilentlyContinue; `
[Environment]::GetEnvironmentVariable("Path", "Machine") -split ";"

If git.exe exists but Get-Command git prints nothing, repair or reinstall Git for Windows so Git is available from the command line, then open a new Windows PowerShell session.

References

  1. Astral uv installation: https://docs.astral.sh/uv/getting-started/installation/
  2. Git for Windows install page: https://git-scm.com/install/windows
  3. Microsoft Windows PowerShell startup documentation: https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell
  4. Microsoft PowerShell 7 installation documentation: https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows
  5. GitLab SSH key documentation: https://docs.gitlab.com/user/ssh/
  6. GitLab.com SSH host key fingerprints: https://docs.gitlab.com/user/gitlab_com/#ssh-host-keys-fingerprints
  7. GitLab deploy-key documentation: https://docs.gitlab.com/user/project/deploy_keys/
  8. TI MSP430 Flasher tool page: https://www.ti.com/tool/MSP430-FLASHER
  9. TI MSP430 Flasher user's guide: https://www.ti.com/document-viewer/lit/html/slau654
  10. TI MSP430 FET Drivers download page: https://software-dl.ti.com/msp430/msp430_public_sw/mcu/msp430/MSP430_FET_Drivers/latest/index_FDS.html
  11. TI myTI account registration: https://www.ti.com/myti/nsdocs/register