This is the multi-page printable view of this section. Click here to print...

For suitable output, we recommend to use Google Chrome (15+) or Microsoft Edge (79+).

As of 2025-07-24

Installation Method

How to install the TWELITE STAGE SDK

1: Folder Structure

2: Platform-specific Notes

2.1: Notes When Installing on Windows

2.2: Notes When Installing on macOS

2.3: Notes When Installing on Linux

2.4: Notes When Installing on Raspberry Pi

Depending on the operating environment, various settings may be required for this application to function properly. If any issues arise, please refer to this document to prepare your environment.

To set up the development environment, it is necessary to install software packages and agree to their licenses. Security settings may also be required.

Although we take great care during distribution, please also verify on your side that the files do not contain viruses or malware.
For security operations (such as whether external applications can be installed), please consult the administrator of your environment.

Please also refer to “Regarding Application Distribution and Execution,” which includes the following:

Verification of the integrity between the original files and downloaded files
Handling of code signing on macOS/Windows

Installation Procedure for TWELITE STAGE SDK

① Obtain the Archive

Download the TWELITE STAGE SDK for each platform (Windows / macOS / Linux) from Download.

On macOS, you can use Homebrew


brew install twelite-stage

The installation destination is ~/MWSTAGE.

② Extract the Archive

Extract the downloaded Zip archive.

Do not include spaces, kanji, hiragana, or other characters outside of half-width digits 0..9, half-width alphabets a..zA..Z, and some symbols -_. in the file path of the extraction destination. Examples for Windows:

NG: C:\work\作業\
NG: C:\Users\user1\work dir\
OK: C:\Work\Work1

③ Check the Files

Check the extracted folder.

The archive extracted on C:\Work is usually expanded to C:\Work\MWSTAGE, but depending on the extraction software, the folder name may differ. Change it if necessary.

In the text, the extracted folder (e.g., C:\Work\MWSTAGE) may be represented as {MWSTAGE Installation}.

The extracted folder {MWSTAGE Installation} contains the following:

TWELITE STAGE APP
- For Windows: TWELITE_Stage.exe (standard version), TWELITE_Stage_VSCode.exe (VSCode compatible version)
- For macOS: TWELITE_Stage.command (standard version), TWELITE_Stage_VSCode.command (VSCode compatible version)
- For Linux: TWELITE_Stage.run (standard version), TWELITE_Stage_VSCode.run (VSCode compatible version)
TWELITE_STAGE - related files of TWELITE STAGE APP
MWSDK - libraries, source code, etc.
Tools - toolchains for building
BIN - .BIN files for TWELITE referenced by the [Select from BIN] menu of TWELITE STAGE APP
log - storage location for logs and database files of TWELITE STAGE APP
flask_wsns_db - simple server using Python, Flask, and sqlite3

For details, see “Folder Structure”.

1 - Folder Structure

About the folder structure of TWELITE STAGE APP

TWELITE STAGE APP operates as the frontend application of TWELITE STAGE SDK.

Here, we explain its folder structure.

MWSTAGE/            : TWELITE STAGE SDK installation
  TWELITE_Stage.??? : Executable (Windows .exe, macOS .command, Linux .run)
  TWELITE_Stage.sav : Configuration file
  TWELITE_Stage.ini : Other settings
  TWELITE_Stage/    : Related files of TWELITE STAGE APP

  MWSDK/            : MWSDK libraries etc.
  BIN/              : Storage destination when [Select BIN file] is used
  log/              : Log and database storage destination

  Tools/            : A set of tools including gcc compiler

  flask_wsns_db/    : Simple server using Python, Flask, sqlite3

`MWSDK` folder

MWSDK/
  Act_samples/        : Sample code using mwx library
  Wks_TweApps/        : Source code of TWELITE APPS
  Act_extras/         : More specialized samples using mwx library, and those referencing other libraries
  TWENET/             : TWENET library (mwx library etc.)
  ChipLib/            : Semiconductor library
  MkFiles/            : Core processing part of Makefile
  docs/               : Library manuals etc.
  LICENSE             : License description of MWSDK
  000manifest         : Version information of MWSDK
  ReleaseNotes.md     : Update history (top page)
  ReleaseNotes_en.md  : Update history (English)
  ReleaseNotes_jp.md  : Update history (Japanese)

The MWSDK folder contains libraries for building TWELITE software, samples, and source code of TWELITE APPS.

`TWELITE_Stage.sav`

Stores the configuration information of TWELITE STAGE APP.

The file name is the TWELITE STAGE APP executable name + .sav.

`TWELITE_Stage.ini`

Details of .ini file are here.

MWSDK= Edit this when you want to specify a different folder instead of the MWSDK/ folder. This is useful when mixing multiple library versions. In the above example, the MWSDK2020_10 folder is used.
LANG= Specify LANG=en to set the display language of TWELITE STAGE APP to English.

Running TWELITE STAGE APP with different settings

Copy TWELITE_Stage.exe (for Windows) with a different file name. For example, if changed to TWS1.exe, it refers to configuration files named TRS1.sav and TRS1.ini.

`BIN` folder

When selecting the [Select from BIN] menu in TWELITE STAGE APP, firmware files (.BIN) in this folder are used.

`log` folder

When running the serial port logging function in TWELITE STAGE APP, log files are stored in this folder.

This folder is also the storage destination for database files when using the graph function and for outputting csv files.

`Tools` folder

Contains cross-compiler toolchains such as gcc, g++.

Platform-specific utilities are also stored in this folder. For details, see Tools/readme.txt.

`flask_wsns_db` folder

Python sample script to access the database created by the sensor graph viewer of TWELITE STAGE APP. This sample allows viewing tables and graphs in a web browser.

For details, see flask_wsns_db/README.html.

Build project folder

This feature is introduced as a non-standard feature. Behavior may differ from the description.

Folder search order

TWELITE STAGE APP searches build project folders (Act_samples etc.) in the following order:

The folder where TWELITE STAGE APP was started
The folder where the TWELITE STAGE APP executable is located
{MWSDK folder}/..
{MWSDK folder}

MWSDK is searched starting from the folder where the TWELITE STAGE APP executable is located.

Wks_Acts

If you create a Wks_Acts folder, this folder is referenced from the [act Build & Rewrite] menu instead of the Act_samples folder.

Wks_Acts is intended to store projects you create yourself.

2 - Platform-specific Notes

Platform-specific notes for installation

This document describes notes to consider when installing the TWELITE STAGE APP on each platform.

2.1 - Notes When Installing on Windows

Notes when installing the TWELITE STAGE APP on Windows

Windows

Environment

The development and operation have been confirmed in the following environment.

Windows 10 Version 1903
Visual Studio 2019 (32bit build)

Handling of Serial Ports

MONOSTICK and TWELITE R series are equipped with FTDI’s USB serial conversion ICs (FT230/FT232 series). To use these, device driver installation may be required.

If the PC does not recognize MONOSTICK or TWELITE R, please install the D2XX driver from https://www.ftdichip.com.

Additional Installation of Visual C++ Runtime Library

In some cases, the Visual C++ redistributable code (runtime library) of Visual Studio 2019 is required.

If an error occurs when starting the application and it does not launch, run TWELITE_Stage¥INSTALL¥VC_redist.x86.exe distributed in this package, or obtain it from Microsoft’s website. Note that the redistributable binary is 32bit.

2.2 - Notes When Installing on macOS

Notes when installing the TWELITE STAGE APP on macOS

macOS

Environment

The development and operation have been confirmed in the following environments.

macOS 10.14 (Mojave, Intel)
macOS 12 (Monterey, Apple Silicon)

Installing Rosetta 2

Rosetta 2 is required for building applications for the BLUE / RED series.


/usr/sbin/softwareupdate --install-rosetta --agree-to-license

The build for the BLUE / RED series uses toolchains such as ba-elf-gcc, but Apple Silicon binaries are not available.

Therefore, please use macOS 27 or earlier when building for the BLUE / RED series.

Dependent Software and Warning Dialogs

If the following issues occur, permission to execute or installation is required for the operation of TWELITE_Stage.command.

Although the toolchain is code-signed, if the code signature is not properly verified, you may be prompted to allow execution individually for each executable in the build toolchain (such as ba-elf-gcc).
The downloaded archive is not signed. At runtime, security warnings may appear indicating that the application was downloaded from the Internet.
You may be asked to allow execution from the path where TWELITE_Stage.command is installed.
A dialog for installing the make utility may appear during build execution.

Additional Installation of make Utility

In some cases, you may need to install the make utility.

Depending on the macOS version and other factors, a different procedure may be necessary.

If an error occurs when running make from the command line (zsh), install the Command Line Tools.


xcode-select --install

Once the installation is complete, enter make and check for the following output message.


make
make: *** No targets specified and no makefile found.  Stop.

Handling Serial Ports

MONOSTICK and TWELITE R series are equipped with USB serial converter ICs (FT230/FT232 series) from FTDI (https://www.ftdichip.com). To use these, device driver installation may be required.

If the serial port does not appear even after launching TWELITE_Stage.command, please unload (disable) the FTDI driver.

This utility not only suppresses loading of the OS standard device driver when MONOSTICK or TWELITE R is inserted, but also suppresses loading of device drivers for other devices with the same USB ID.

You can download D2xxHelper from https://www.ftdichip.com/Drivers/D2XX.htm. The same is also included in the TWELITE_Stage/INSTALL folder of the TWELITE STAGE SDK.

Reference: Manual Unloading of FTDI Device Driver

To unload FTDI-related drivers, execute the following command.


sudo kextunload -b com.apple.driver.AppleUSBFTDI

2.3 - Notes When Installing on Linux

Notes when installing the TWELITE STAGE APP on Linux

Linux

The USB device ID of TWELITE R2 has changed from the conventional 0403:6001 to 0403:6015. You need to add udev settings.

A 32-bit version is not provided.

Linux environments differ in the types of packages provided depending on the distribution and version. You may need to install packages or configure settings individually.

Please refer to general information using error messages as clues.

Environment

Development and operation have been confirmed on the following environments.

Ubuntu 16.04, 18.04, 20.04
NNLinux Beta8 64bit
CentOS 7

Handling Serial Ports

To recognize MONOSTICK or TWELITE-R from TWELITE STAGE, you need to unload the ftdi_sio module and grant read/write permissions to the USB device.

The USB device IDs are shown below.

Vendor ID 0x0403
Product ID 0x6001 (MONOSTICK, TWELITE R) or 0x6015 (TWELITE R2)

We provide udev setting scripts (for Ubuntu, CentOS) to automate this configuration.

Copy the definitions to /etc/udev/rules.d and reload the settings. After setting, unplug and replug the USB device, then run TWELITE_Stage.run. If the USB device appears on the initial screen, the settings have been applied.

Ubuntu 16.04, 18.04, 20.04


cd ./MWSTAGE/TWELITE_Stage/INSTALL/ubuntu/
sudo ./set_udev_sudo.sh

Definition file (line breaks added for readability)

ACTION=="add",
   ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001",
   MODE="0666",
   RUN+="/bin/sh -c 'rmmod ftdi_sio && rmmod usbserial'"
ACTION=="add",
   ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015",
   MODE="0666",
   RUN+="/bin/sh -c 'rmmod ftdi_sio && rmmod usbserial'"

CentOS 7


cd ./MWSTAGE/TWELITE_Stage/INSTALL/centos/
sudo ./set_udev_sudo.sh

Definition file (line breaks added for readability)

ACTION=="add",
   ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001",
   MODE="0666",
   RUN+="/bin/sh -c '/usr/sbin/rmmod ftdi_sio'"
ACTION=="add",
   ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015",
   MODE="0666",
   RUN+="/bin/sh -c '/usr/sbin/rmmod ftdi_sio'"

Registering the Application

You may not be able to run TWELITE_Stage.run from a file icon on the desktop. This is because the system may not recognize TWELITE_Stage.run as an executable.

Ubuntu 16.04, 18.04, 20.04

We provide a script to generate definition files for Ubuntu.


cd ./MWSTAGE/TWELITE_Stage/INSTALL/ubuntu/
./make_launch_icon.sh

This script creates a .desktop file (application definition) in $HOME/.local/share/applications.

After running the script, the TWELITE STAGE icon will be added to the application list.

2.4 - Notes When Installing on Raspberry Pi

Notes for installing the TWELITE STAGE APP on Raspberry Pi

RasPi

TWELITE STAGE APP runs on Raspberry Pi except for some models.

Supports mouse and touch screen.
Comes with a build toolchain, allowing compilation.
In addition to the X11 version executable, there is a framebuffer version (nox), as well as a lightweight version that omits translucent effects and others.

Depending on the OS type, version, and installation status of your Raspberry Pi, it may not work or may require recompilation.

Environment

The development and operation have been confirmed in the following environment.

Hardware

Raspberry Pi 3 Model B
LCD Screen: Raspberry Pi Touch Display (7")

Software

Raspberry PI OS (32bit) Lite (Version: August 2020)

Known Issues and Limitations

On the first startup, /dev/serial0 may fail to operate.
Operation of /dev/serial0 on Raspberry Pi 4B has not been verified.
Operation of the touchscreen on Raspberry Pi 4B has not been verified.
Input strings to TWELITE STAGE are also passed as-is to shells or getty running on /dev/tty1. It is recommended to start from /dev/tty1.
It may be affected by other installed or running programs (such as X11).

Extracting the Archive

Extract the downloaded archive file into a folder whose path does not contain spaces or Japanese characters.

Below, it is extracted into the Raspberry Pi home folder.


cd /home/pi
unzip MWSTAGE2020_XX_YYYY.zip

Folder Structure

../MWSTAGE
     TWELITE_Stage.run    TWELITE_Stage app
     BIN/                 Firmware BIN files
     MWSDK/               MWSDK libraries, etc.
     TWELITE_Stage/       TWELITE_Stage app related files

Device Drivers

To recognize MONOSTICK or TWELITE R from TWELITE STAGE, it is necessary to unload the ftdi_sio module and grant read/write permissions to the USB device.

The USB device IDs are as follows:

Vendor ID 0x0403
Product ID 0x6001 (MONOSTICK, TWELITE R) or 0x6015 (TWELITE R2)

A udev configuration script is provided to automate this setting. Copy the definition to /etc/udev/rules.d and reload the settings. After setting, unplug and plug the USB device before running TWELITE_Stage.run. If the USB device is displayed on the screen immediately after startup, the setting has been applied.


cd ./MWSTAGE/TWELITE_Stage/INSTALL/ubuntu/
sudo ./set_udev_sudo.sh

Definition file (formatted with line breaks for readability)

ACTION=="add",
   ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001",
   MODE="0666",
   RUN+="/bin/sh -c 'rmmod ftdi_sio && rmmod usbserial'"
ACTION=="add",
   ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015",
   MODE="0666",
   RUN+="/bin/sh -c 'rmmod ftdi_sio && rmmod usbserial'"

Handling Serial Ports

In the above environment, /dev/serial0 can be used by configuring the serial port via raspi-config.


sudo raspi-config

From the menu

  "3 Interface Options    Configure connections to peripherals"
  →"P6 Serial Port Enable/disable shell messages on the serial connection"

Select as follows to disable login shell usage and enable hardware.

  "Would you like a login shell to be accessible over serial?" -> 
  "Would you like the serial port hardware to be enabled?" →

Wiring Example

 [TWELITE]               [Raspberry Pi]
  GND  ------------------ Ground (#6,#9,#14,#20,#25,#30,#34,#39 one of these)
  TXD(DIO6,DIP#10) ------ GPIO15/UART0 RXD (#10)
  PRG(SPIMISO,DIP#7) ---- GPIO23 (#16)
  RXD(DIO7,DIP#3) ------- GPIO14/UART0 TXD (#8)
  RST(RESETN,DIP#21) ---- GPIO22 (#15)
  VCC  ------------------ 3V3 (#1,#17 one of these)
  SET(DIO12,DIP#15) ----- GPIO12 (#32)

Please refer to the manuals of both TWELITE and Raspberry Pi.
DIP# refers to the pin number of the TWELITE DIP.
The above wiring does not guarantee stable operation of TWELITE.

Starting TWELITE STAGE APP

The framebuffer version (nox) does not work on the X11 desktop. Please exit X11.
Run TWELITE_Stage.run. The TWELITE STAGE APP will be displayed on the screen.

Notes

Supports mouse and touch panel.
Input characters in the TWELITE STAGE APP may also be displayed on the console screen.

Others

`/dev/dri` Error

If the following error appears when starting TWELITE_Stage.run, you can ignore it.

  "The path /dev/dri/ cannot be opened or is not available"

Insufficient Memory

If the number of CPUs is 4 or more, parallel compilation will be executed with one less than the number of CPUs during build (3 parallel for 4 cores). Insufficient memory may occur in some cases. In that case, please change the number of parallel jobs.

Raspberry Pi 4

Please select a 32-bit OS.

Notes on buster

It is necessary to enable OpenGL-related drivers.

Select Advanced Settings → A2 GL Driver → G2 GL (Fake KMS) in raspi-config
Install the libgles-dev package

Raspberry Pi OS (bookworm)

As of June 2024, Raspberry Pi OS (32bit, bookworm) has a bug where pin control cannot be performed and modules cannot be recognized or operated due to Linux kernel updates.

Also, in bookworm, startup failures due to errors related to libccm and others have been confirmed, but may be resolved by running the following commands.


sudo apt update
sudo apt install --reinstall libraspberrypi0 libraspberrypi-dev libraspberrypi-doc libraspberrypi-bin

At this time, rebooting may cause lightdm to fail to start. In that case, please try installing raspberrypi-ui-mods.


sudo apt update
sudo apt install raspberrypi-ui-mods

We apologize for the inconvenience, but please use Raspberry Pi OS (32bit, bullseye) for the time being.

Addendum: A beta version of the TWELITE STAGE app compatible with Raspberry Pi OS (bookworm) has been created.

[How to apply the 32-bit patch]


cd MWSTAGE
wget https://twelite.net/files/TWELITE_Stage_Wayland.run.zip
unzip TWELITE_Stage_Wayland.run.zip
./TWELITE_Stage_Wayland.run

Main file: TWELITE_Stage_Wayland.run.zip
- SHA256: 76da281f80dc998fde1acb9eeb4d5168179f810b03342feb8b3e8ad644a978a2

[How to apply the 64-bit patch]

For the 64-bit version, the compiler is also replaced with the 64-bit version.


cd MWSTAGE
wget https://twelite.net/files/TWELITE_Stage_Wayland_64.run.zip
unzip TWELITE_Stage_Wayland_64.run.zip
mv Tools/ba-elf-ba2-r36379 Tools/ba-elf-ba2-r36379-bkup32
wget https://twelite.net/files/ba-elf-ba2-r36379_aarch64.tgz
tar -xzf ba-elf-ba2-r36379_aarch64.tgz
mv ba-elf-ba2-r36379 Tools/
./TWELITE_Stage_Wayland_64.run

Main file: TWELITE_Stage_Wayland_64.run.zip
- SHA256: 2f784b3d667ccb08b9cc9fe5eda8cd48e37c2e11c1747718087fe279be693a0f
Toolchain: ba-elf-ba2-r36379_aarch64.tgz
- SHA256: 81a9546c2d1d77344358426a1eefa275a08e24d8b497d2faefce07d497776a45

Installation Method

Installation Procedure for TWELITE STAGE SDK

① Obtain the Archive

② Extract the Archive

③ Check the Files

1 - Folder Structure

MWSDK folder

TWELITE_Stage.sav

TWELITE_Stage.ini

Running TWELITE STAGE APP with different settings

BIN folder

log folder

Tools folder

flask_wsns_db folder

Build project folder

Folder search order

Wks_Acts

2 - Platform-specific Notes

2.1 - Notes When Installing on Windows

Environment

Handling of Serial Ports

Additional Installation of Visual C++ Runtime Library

2.2 - Notes When Installing on macOS

Environment

Installing Rosetta 2

Dependent Software and Warning Dialogs

Additional Installation of make Utility

Handling Serial Ports

Reference: Manual Unloading of FTDI Device Driver

2.3 - Notes When Installing on Linux

Environment

Handling Serial Ports

Ubuntu 16.04, 18.04, 20.04

CentOS 7

Registering the Application

Ubuntu 16.04, 18.04, 20.04

2.4 - Notes When Installing on Raspberry Pi

Environment

Hardware

Software

Known Issues and Limitations

Extracting the Archive

Folder Structure

Device Drivers

Handling Serial Ports

Wiring Example

Starting TWELITE STAGE APP

Notes

Others

/dev/dri Error

Insufficient Memory

Raspberry Pi 4

Raspberry Pi OS (bookworm)

`MWSDK` folder

`TWELITE_Stage.sav`

`TWELITE_Stage.ini`

`BIN` folder

`log` folder

`Tools` folder

`flask_wsns_db` folder

`/dev/dri` Error