1. Software prerequisite

At first, you could install the MadMachine extension for Visual Studio Code. It allows you to create a new project, compile and download it to your board.

info

We now support:

• macOS 13.0+
• Ubuntu 22.04 and 24.04 (x64)
• Windows 11 (x64, with a bit of extra setup — more details coming soon)

1. Install USB-Serial driver

1. Download the macOS driver and unzip it.
2. Install the dmg format driver in the zip file.

3. Drag CH34xVCPDriver into Application folder.

4. Open LaunchPad and open the CH34xVCPDriver app.

   Click Open if there is a popup window.

   

5. Click the Install button.

If there is a popup message saying System Extension Blocked.

Click Open System Settings button.

Click Allow.

The driver is installed successfully.

info

1. To uninstall the driver, remove the app to Trash.
2. Restart the computer before reinstalling the driver.

After the driver is installed, you should see the port tty.wchusbserialx in serial monitor if you connect your board to the computer.

2. Download mm-sdk

Download the mm-sdk according to your operating system and unzip it.

3. Setting up the Swift development enviroment

macOS

Since the Swift toolchain included in Xcode doesn't contain the embedded libraries, you need to install latest Swift toolchain release from Swift.org

1. Download and install Xcode.
2. Download and install the Package Installer (release/6.1.2) of the Swift toolchain(.pkg), it will be installed to /Library/Developer/Toolchains.

Linux

1. Install required dependencies:

Ubuntu 22.04

sudo apt-get install \
          binutils \
          git \
          gnupg2 \
          libc6-dev \
          libcurl4-openssl-dev \
          libedit2 \
          libgcc-11-dev \
          libpython3-dev \
          libsqlite3-0 \
          libstdc++-11-dev \
          libxml2-dev \
          libz3-dev \
          pkg-config \
          python3-lldb-13 \
          tzdata \
          unzip \
          zlib1g-dev

Ubuntu 24.04

sudo apt-get install \
          binutils \
          git \
          gnupg2 \
          libc6-dev \
          libcurl4-openssl-dev \
          libedit2 \
          libgcc-13-dev \
          libncurses-dev \
          libpython3-dev \
          libsqlite3-0 \
          libstdc++-13-dev \
          libxml2-dev \
          libz3-dev \
          pkg-config \
          tzdata \
          unzip \
          zlib1g-dev

2. Download the tarball package (.tar.gz) of the latest Swift toolchain release.
3. Unzip the .tar.gz file — the extracted directory will be the Swift toolchain path.

4. Install MadMachine extension for VS Code

1. Open the Visual Studio Code. Click the Extension icon on the left activity bar.
2. Enter MadMachine in the search box to find the extension in its marketplace.
3. Click the Install button.

info

For advanced users, you could edit your code wherever you like and use the mm-sdk to compile your code.

4. Click ⚙️ / Extension Settings to open the settings.

The extension relies on the mm-sdk to do all its work. You need to indicate sdk's path before using the extension.

5. Enter the path of the sdk in the box that matches your operating system.

6. Enter the path of the Swift toolchain in the box that matches the location (optional, /Library/Developer/Toolchains/swift-latest.xctoolchain is the default on macOS).

   • The mm-sdk will look for the Swift toolchian in the following order:
     1. The toolchain path specified in the extension settings.
     2. The path set by TOOLCHAIN enviroment variable.
     3. The default Swift toolchain path on your operating system.

macOS

Linux

important

Make sure the sdk path is correct, or the extension won't work.

Now, the extension gets ready👏.

The extension is at the bottom of the Explorer panel. All you need for your project is these three buttons:

• Build: build your project after you finish the code. If there are any errors, you can modify your code according to the message in the terminal.
• Download: download the generated file after building your project.
• Copy Resources: copy the entire Resources directory to the specified file system (Flash: /lfs or SD card: /SD:)
• New Project: create a new MadMachine project. You will choose the project type and the board type.