Soracom Orbit

Environment Setup

When developing WASM modules for Orbit, you can generally use any programming language that supports binary output in WASM format. However, as development environments that support binary output are not yet common, Soracom recommends using a Docker container (hereafter development container) to simplify the development environment setup.

This guide describes the process for setting up a development environment using a Docker development container with Visual Studio Code in order to start developing WASM modules for Orbit.

For more information on developing with Visual Studio Code and a development container, refer to the Developing inside a Container guide.

---

Prerequisites

Before setting up the development container, you will need to install the following tools:

• Docker
• Visual Studio Code

As Docker and Visual Studio Code are available for all major platforms, this guide should apply regardless of what host OS you are using. Soracom has tested the development environment with the following configuration:

• OS: macOS Sonoma 14.2 (23C64)
• Visual Studio Code: 1.85.1
• Docker: Rancher Desktop 1.11.1

---

Creating a SAM User

Orbit module development involves deploying WASM modules to the Soracom platform within your Soracom account. You can upload compiled WASM modules using the User Console, however as this is cumbersome we recommend integrating the deployment process into your development environment.

In order to access your Soracom account from your development environment, you must set up an authentication method. For security, we recommend creating a SAM User with limited permissions, instead of authenticating against your root account. Your SAM User will also need an AuthKey in order to enable programmatic access.

1. Login to the User Console. Click your account menu, then select Security.

2. From the Security screen, click the Users tab. Then click the Create a user button.

3. Enter a unique Name for the SAM user, such as orbit-dev. You can also add a Description to help identify this user. Then click the Create button. Your new SAM user will be added to the list of users.

4. Click the name of the SAM user you just created.

5. From the SAM User settings page, find the Inline permissions panel, and enter the following Permissions:

   {
     "statements": [
       {
         "api": ["Soralet:*", "Groups:listGroups", "Groups:getGroup"],
         "effect": "allow"
       }
     ]
   }

   Then click the Save button.

6. Next, click the Authentication tab.

7. From the AuthKeys panel, click the Generate an AuthKey button. An AuthKey ID and AuthKey Secret key pair will be automatically generated. Make a note of both the AuthKey ID and the AuthKey Secret.

Your SAM user is now ready and can be used to authenticate your account during Orbit module development.

---

Setting up the Soracom CLI

Next, we need a way to access Soracom directly from our development environment. We recommend installing the Soracom CLI tool and using the new SAM user for authentication.

1. Open the soracom-cli repository and download the latest release for your platform. For developing Orbit modules, you must use soracom-cli version 0.5.5 or later.

2. Install the soracom executable to your environment. You may need to configure your environment's PATH variable to include the location of the soracom executable. Once configured, you should be able to check the version of soracom-cli:

   soracom version
   >SORACOM API client v0.5.5

3. Now run soracom configure to set up authentication:

   soracom configure
   >--- SORACOM CLI setup ---
   >This will create a directory ~/.soracom if it does not exist yet and place 'default.json' >in it.
   >
   >Please select which coverage type to use.
   >
   >1. Global
   >2. Japan
   >
   >select (1-2) > _

   Enter 1 or 2 for the coverage region where you intend to deploy Orbit modules.

4. Next you will be asked to configure CLI authentication:

   >Please select which authentication method to use.
   >
   >1. Input AuthKeyId and AuthKey * Recommended *
   >2. Input Operator credentials (Operator Email and Password)
   >3. Input SAM credentials (OperatorId, User name and Password)
   >
   >select (1-3) > _

   Enter 1 to use AuthKeyId and AuthKey authentication, and enter the AuthKey ID and AuthKey Secret that you generated for your SAM user earlier.

The Soracom CLI tool is now configured to access your Soracom account using your SAM user's programmatic access credentials.

---

Setting up your Environment

Regardless of which programming language you intend to use to develop WASM modules, you will need to set up your development environment:

1. Download the Soracom Orbit SDK and extract the orbit-development-environment-2023-12.zip file to any directory on your machine.

   This package contains the Orbit SDKs for AssemblyScript, Rust, and C/C++, each in their respective subdirectories.

2. Open the /assemblyscript, /rust, or /c subdirectory using VS Code.

   If you do not already have the Remote - Containers VS Code extension installed, you will be prompted to install it. Click Install All.

   If you are using Windows and configure both HOME and USERPROFILE environment variables, VS Code will fail to start. Use only one of these, which contains.soracom directory and unset the other.

   If your VS Code user setting includes "extensions.ignoreRecommendations": true, you will not receive the prompt to install the recommended features. You will need to install the Remote Containers extension manually.

   You can also create a separate VS Code user directory in order to keep your Orbit module development environment separate from your existing VS Code configuration. See the Tips section below.

3. Next, you will be prompted to reopen the VS Code workspace in the development container. Click Reopen in Container. The Docker development container for Orbit module development will be created. The development container creation progress will be displayed, and may take several minutes to complete.

Additional Steps for AssemblyScript

If you are developing using AssemblyScript, you also need to initialize NPM packages inside the development container:

4. After creating and starting the development container, run the init script defined in package.json using one of the following methods:

   • In VS Code, open the NPM Scripts view, select the init script, and click Run
   • In VS Code, open the integrated terminal and run npm run init

   You should see terminal output similar to the following:

   >> Executing task: npm run init <
   >
   >> orbit-development-environment-assemblyscript@0.0.1 init /.../>orbit-development-environment/assemblyscript
   >> npm ci
   >
   >npm WARN prepare removing existing node_modules/ before installation
   >added 892 packages in 7.776s
   >
   >Terminal will be reused by tasks, press any key to close it.

Your development environment is now set up and ready for Orbit module development.

---

Tips

Using a different VS Code User

If you already use VS Code and want to keep your Orbit module development environment separate from your existing development environment, you can simply create a new user directory for VS Code.

For example, create your user directory directly inside the Orbit SDK folders:

mkdir vscode-{data,extensions}-dir

Now you can open VS Code, specifying the new user directories:

code --user-data-dir vscode-user-data-dir --extensions-dir vscode-extensions-dir assemblyscript

Since the directories are empty, VS Code will initialize a new user profile, separate from any other user settings you have with your existing VS Code environment.

For your convenience, the Orbit SDK also includes a launch.example shell script that wraps the necessary parameters in a simple command:

cp launch.example launch  # Copy the launch script
vi launch                 # Edit the parameters
./launch assemblyscript   # Launch the AssemblyScript development environment
./launch rust             # Launch the Rust development environment
./launch c                # Launch the C/C++ development environment
./launch tinygo           # Launch the TinyGo development environment

Mounting a Host Directory

When you open a development environment, VS Code will show the filesystem within the development container itself, rather than the filesystem of your local (host) machine. You may want to mount a directory from your host machine inside the container, so that you can either add external libraries or assets, or save any code developed within the container on your local filesystem.

To mount a host directory within the development container, edit the .devcontainer/devcontainer.json file. For example, you can mount your local machine's ~/.ssh directory:

{
  "name": "SORACOM Orbit Development Container",
  // ...
  "mounts": [
    "source=${localEnv:HOME}${localEnv:USERPROFILE}/.ssh,target=/root/.ssh,type=bind,consistency=cached"
  ]
}

For Rust, mounting ~/.cargo to a directory on the host can help speed up the build:

{
  "name": "SORACOM Orbit Development Container",
  // ...
  "mounts": [
    "source=${localEnv:HOME}${localEnv:USERPROFILE}/.cargo/git,target=/workspaces/.cargo/git,type=bind,consistency=cached",
    "source=${localEnv:HOME}${localEnv:USERPROFILE}/.cargo/registry,target=/workspaces/.cargo/registry,type=bind,consistency=cached"
  ]
}

For more information about mounting host directories in containers, see the VS Code Advanced Container Configuration documentation.