Manuals

• 1: TWELITE STAGE SDK
• 1.1: Installation Method
• 1.1.1: Folder Structure
• 1.1.2: Platform-specific Notes
• 1.1.2.1: Notes When Installing on Windows
• 1.1.2.2: Notes When Installing on macOS
• 1.1.2.3: Notes When Installing on Linux
• 1.1.2.4: Notes When Installing on Raspberry Pi
• 1.2: TWELITE STAGE APP
• 1.2.1: TWELITE STAGE APP Manual
• 1.2.1.1: Obtaining the Package
• 1.2.1.2: How to Use
• 1.2.1.2.1: Key and Mouse Operations
• 1.2.1.2.2: Screen Operations
• 1.2.1.2.2.1: Serial Port Selection
• 1.2.1.2.2.2: Main Menu
• 1.2.1.2.2.2.1: Viewer
• 1.2.1.2.2.2.1.1: Terminal
• 1.2.1.2.2.2.1.2: Standard App Viewer
• 1.2.1.2.2.2.1.3: Graph
• 1.2.1.2.2.2.1.3.1: Accelerometer Real-Time Graph
• 1.2.1.2.2.2.1.3.2: Sensor Graph
• 1.2.1.2.2.2.1.4: Simple Monitor
• 1.2.1.2.2.2.1.4.1: CUE Viewer
• 1.2.1.2.2.2.1.4.2: ARIA Viewer
• 1.2.1.2.2.2.1.4.3: Glancer
• 1.2.1.2.2.2.1.5: Commander
• 1.2.1.2.2.2.2: Write App Firmware
• 1.2.1.2.2.2.2.1: Select from BIN
• 1.2.1.2.2.2.2.2: act Build & Write
• 1.2.1.2.2.2.2.3: TWELITE APPS Build & Write
• 1.2.1.2.2.2.2.4: Act_extras
• 1.2.1.2.2.2.2.5: Folder (Specify)
• 1.2.1.2.2.2.2.6: Last (Re-execute)
• 1.2.1.2.2.2.2.7: Build & Write Screen
• 1.2.1.2.2.2.3: Interactive Settings Mode
• 1.2.1.2.2.2.4: Settings of TWELITE STAGE
• 1.2.1.2.2.2.5: Select SERIAL port
• 1.2.1.2.3: Logging Function
• 1.2.1.3: Detailed Specifications
• 1.2.1.3.1: Detailed Settings with Command-line Arguments and ini Files
• 1.2.1.3.2: Environment Variables
• 1.2.1.3.3: Adding Project Descriptions with 000desc.txt
• 1.2.1.4: License
• 1.2.1.5: Revision History
• 1.3: TWELITE APPS
• 1.3.1: TWELITE APPS (Unified) Manual
• 1.3.1.1: TWELITE APPS (Unified) Manual
• 1.3.2: Extremely Simple! Standard App Manual
• 1.3.2.1: Extremely Simple! Standard App Manual
• 1.3.2.1.1: Pin Assignments of Extremely Simple! Standard App
• 1.3.2.1.2: Operating Modes of Extremely Simple! Standard App
• 1.3.2.1.3: Alternative Baud Rate Setting for Extremely Simple! Standard App
• 1.3.2.1.4: UART Function of Extremely Simple! Standard App
• 1.3.2.1.5: Interactive Mode (Extremely Simple! Standard App)
• 1.3.3: Parent and Repeater App Manual
• 1.3.3.1: Parent and Repeater App Manual
• 1.3.3.1.1: Operating Modes of Parent and Repeater App
• 1.3.3.1.1.1: Parent Mode of Parent and Repeater App
• 1.3.3.1.1.1.1: Messages of Parent and Repeater Apps
• 1.3.3.1.1.1.1.1: Output from the Extremely Simple! Standard App (Parent and Repeater App)
• 1.3.3.1.1.1.1.2: Output from Remote Control App (Parent and Repeater App)
• 1.3.3.1.1.1.1.3: Output from Serial Communication App (Parent and Repeater App)
• 1.3.3.1.1.1.1.4: Output from Pal/Cue/Aria Apps (Parent and Repeater App)
• 1.3.3.1.1.1.1.4.1: Output from PAL App (Parent and Repeater App)
• 1.3.3.1.1.1.1.4.2: Output from CUE App (Parent and Repeater App)
• 1.3.3.1.1.1.1.4.3: Output from Aria App (Parent and Repeater App)
• 1.3.3.1.1.1.1.4.4: Details of Output from Pal, Cue, and Aria Apps (Parent and Repeater App)
• 1.3.3.1.1.1.1.5: Output from act (Parent and Repeater App)
• 1.3.3.1.1.1.1.6: Output from Wireless Tag App (Parent and Repeater App)
• 1.3.3.1.1.1.2: Transmit Command of Parent and Repeater App
• 1.3.3.1.1.1.2.1: Input to the Extremely Simple! Standard App (Parent and Repeater App)
• 1.3.3.1.1.1.2.2: Input to the Serial Communication App (Parent and Repeater App)
• 1.3.3.1.1.1.2.3: Input to the PAL App (Notification PAL) (Parent and Repeater App)
• 1.3.3.1.1.2: Repeater Mode of Parent and Repeater App
• 1.3.3.1.2: Interactive Mode (Parent and Repeater App)
• 1.3.3.2: Parent and Repeater App Manual
• 1.3.3.2.1: Operating Modes of Parent and Repeater App
• 1.3.3.2.1.1: Parent Mode of Parent and Repeater App
• 1.3.3.2.1.1.1: Messages of Parent and Repeater Apps
• 1.3.3.2.1.1.1.1: Output from the Extremely Simple! Standard App (Parent and Repeater App)
• 1.3.3.2.1.1.1.2: Output from Remote Control App (Parent and Repeater App)
• 1.3.3.2.1.1.1.3: Output from Serial Communication App (Parent and Repeater App)
• 1.3.3.2.1.1.1.4: Output from Pal/Cue/Aria Apps (Parent and Repeater App)
• 1.3.3.2.1.1.1.4.1: Output from PAL App (Parent and Repeater App)
• 1.3.3.2.1.1.1.4.2: Output from CUE App (Parent and Repeater App)
• 1.3.3.2.1.1.1.4.3: Output from Aria App (Parent and Repeater App)
• 1.3.3.2.1.1.1.4.4: Details of Output from Pal, Cue, and Aria Apps (Parent and Repeater App)
• 1.3.3.2.1.1.1.5: Output from act (Parent and Repeater App)
• 1.3.3.2.1.1.1.6: Output from Wireless Tag App (Parent and Repeater App)
• 1.3.3.2.1.1.2: Transmit Command of Parent and Repeater App
• 1.3.3.2.1.1.2.1: Input to the Extremely Simple! Standard App (Parent and Repeater App)
• 1.3.3.2.1.1.2.2: Input to the Serial Communication App (Parent and Repeater App)
• 1.3.3.2.1.1.2.3: Input to the PAL App (Notification PAL) (Parent and Repeater App)
• 1.3.3.2.1.2: Repeater Mode of Parent and Repeater App
• 1.3.3.2.2: Interactive Mode (Parent and Repeater App)
• 1.3.4: Remote Control App Manual
• 1.3.4.1: Remote Control App Manual
• 1.3.4.1.1: Pin Assignment of Remote Control App
• 1.3.4.1.2: Remote Control App Operating Modes
• 1.3.4.1.3: Remote Control App Alternative Baud Rate Setting
• 1.3.4.1.4: Remote Control App UART Function
• 1.3.4.1.5: Custom Default Feature of Remote Control App
• 1.3.4.1.6: Pairing Function of Remote Control App
• 1.3.4.1.7: Interactive Mode (Remote Control App)
• 1.3.5: Serial Communication App Manual
• 1.3.5.1: Serial Communication App Manual
• 1.3.5.1.1: Pin Assignments of Serial Communication App
• 1.3.5.1.2: Communication Modes of Serial Communication App
• 1.3.5.1.2.1: Serial Communication App Format Mode (ASCII)
• 1.3.5.1.2.1.1: 0xDB Command in Serial Communication App Format Mode (ASCII)
• 1.3.5.1.2.2: Serial Communication App Format Mode (Binary)
• 1.3.5.1.2.2.1: 0xDB Command in Serial Communication App Format Mode (Binary)
• 1.3.5.1.2.3: Serial Communication App Chat Mode
• 1.3.5.1.2.4: Serial Communication App Transparent Mode
• 1.3.5.1.2.5: Serial Communication App Header Transparent Mode
• 1.3.5.1.3: Interactive Mode (Serial Communication App)
• 1.3.5.1.4: Notes on Communication in Serial Communication App
• 1.3.5.1.5: Custom Default Feature of Serial Communication App
• 1.3.5.2: Serial Communication App Manual
• 1.3.5.2.1: Pin Assignments of Serial Communication App
• 1.3.5.2.2: Communication Modes of Serial Communication App
• 1.3.5.2.2.1: Serial Communication App Format Mode (ASCII)
• 1.3.5.2.2.1.1: 0xDB Command in Serial Communication App Format Mode (ASCII)
• 1.3.5.2.2.2: Serial Communication App Format Mode (Binary)
• 1.3.5.2.2.2.1: 0xDB Command in Serial Communication App Format Mode (Binary)
• 1.3.5.2.2.3: Serial Communication App Chat Mode
• 1.3.5.2.2.4: Serial Communication App Transparent Mode
• 1.3.5.2.2.5: Serial Communication App Header Transparent Mode
• 1.3.5.2.3: Custom Default Feature of Serial Communication App
• 1.3.5.2.4: Notes on Communication in Serial Communication App
• 1.3.5.2.5: Interactive Mode (Serial Communication App)
• 1.3.6: Cue App Manual
• 1.3.6.1: Cue App Manual
• 1.3.6.1.1: Cue App Operating Modes
• 1.3.6.1.1.1: Cue App TWELITE CUE Mode
• 1.3.6.1.1.2: Cue App Motion Sensor Pal Mode
• 1.3.6.1.1.3: Cue App Open/Close Sensor Pal Mode
• 1.3.6.1.2: Cue App Settings
• 1.3.6.1.2.1: Cue App Settings via OTA
• 1.3.6.1.2.2: Cue App Settings via TWELITE R2/R3
• 1.3.6.1.2.3: Interactive Mode (Cue App)
• 1.3.7: Aria App Manual
• 1.3.7.1: Aria App Manual
• 1.3.7.1.1: How to Use the Aria App
• 1.3.7.1.1.1: Checking Operation of Aria App
• 1.3.7.1.1.2: Aria App Operating Modes
• 1.3.7.1.1.2.1: Aria App TWELITE ARIA Mode
• 1.3.7.1.1.2.2: Aria App Open/Close Sensor Pal Mode
• 1.3.7.1.2: Aria App Settings
• 1.3.7.1.2.1: OTA Settings for Aria App
• 1.3.7.1.2.2: Settings for Aria App using TWELITE R2/R3
• 1.3.7.1.3: Interactive Mode (ARIA App)
• 1.3.8: Pal App Manual
• 1.3.8.1: Pal App Manual
• 1.3.8.1.1: Interactive Mode (Pal App)
• 1.4: act Samples
• 1.4.1: act Samples
• 1.4.1.1: act0..4
• 1.4.1.2: Scratch
• 1.4.1.3: Slp_Wk_and_Tx
• 1.4.1.4: Parent_MONOSTICK
• 1.4.1.5: PingPong
• 1.4.1.6: BRD_APPTWELITE
• 1.4.1.7: BRD_I2C_TEMPHUMID
• 1.4.1.8: BRD_ARIA
• 1.4.1.9: PAL_AMB
• 1.4.1.10: PAL_AMB-usenap
• 1.4.1.11: PAL_AMB-behavior
• 1.4.1.12: PAL_MAG
• 1.4.1.13: PAL_MOT-single
• 1.4.1.14: PAL_MOT-fifo
• 1.4.1.15: PulseCounter
• 1.4.1.16: WirelessUART
• 1.4.1.17: Universal Receiver
• 1.4.1.18: Unit_???
• 1.5: Revision History
• 2: Flashing Firmware with Python
• 2.1: Flashing Firmware with Python
• 2.2: Flashing Firmware with Python
• 2.3: Flashing Firmware with Python
• 3: TWELITE SPOT / ESP32
• 3.1: Overview of Pre-installed Applications
• 3.2: Installation Methods Considering Wireless Performance
• 3.3: How to Set Up a Firmware Development Tools
• 3.3.1: How to Set Up Development Tools With Arduino IDE 1.x
• 3.3.1.1: Installing Arduino IDE 1.x
• 3.3.1.2: Installing Arduino core for the ESP32
• 3.3.1.3: Configuring Arduino core for the ESP32
• 3.3.1.4: Installing the MWings Library
• 3.4: How to Write Firmware
• 3.4.1: How to Write Firmware to ESP32
• 3.4.1.1: How to Write Sketches to ESP32
• 3.4.1.2: How to Write Files to ESP32
• 3.4.1.3: How to Specify the Partition Table for Writing to ESP32
• 3.4.2: How to Write Firmware to TWELITE
• 3.4.3: How to Initialize Firmware
• 3.4.3.1: How to Initialize ESP32 Firmware
• 3.4.3.2: How to Initialize TWELITE Firmware
• 3.5: Sample Sketches Overview
• 3.5.1: Explanation of Sketches Communicating with TWELITE
• 3.5.1.1: Acquire and Control Data from the Extremely Simple! Standard App
• 3.5.1.1.1: Acquire and Control Data from the Extremely Simple! Standard App
• 3.5.1.1.2: Acquire and Control Data from the Extremely Simple! Standard App
• 3.5.1.1.3: Acquire and Control Data from the Extremely Simple! Standard App
• 3.5.1.2: Retrieve Data from Queue App
• 3.5.1.2.1: Get Data from the Queue App
• 3.5.1.2.2: Acquiring Data from the Queue App
• 3.5.1.2.3: Retrieve Data from Queue App
• 3.5.1.3: Retrieve Data from the ARIA App
• 3.5.1.3.1: Retrieve Data from Aria App
• 3.5.1.3.2: Retrieve Data from ARIA App
• 3.5.1.3.3: Retrieve Data from ARIA App
• 3.5.2: Sketches Using TWELITE with Wi-Fi
• 3.5.2.1: Pre-installed Sketch
• 3.5.2.1.1: Pre-installed Sketch
• 3.5.2.1.2: Pre-installed Sketch
• 3.5.2.2: Relay for WebSocket
• 3.5.2.2.1: Relay for WebSocket
• 3.5.2.3: Using the REST API
• 3.5.2.3.1: Using REST API
• 3.5.2.3.2: Using the REST API
• 3.5.2.4: Using Google Sheets
• 3.5.2.4.1: Using Google Sheets
• 3.5.2.5: Graph Display Using ThingSpeak
• 3.5.2.5.1: Graph Display with ThingSpeak
• 4: TWELITE WINGS API / MWings
• 4.1: TWELITE Wings API / MWings for Python
• 4.1.1: TWELITE Wings API / MWings for Python
• 4.2: TWELITE Wings API / MWings for 32-bit Arduinos
• 4.2.1: TWELITE Wings API / MWings for 32-bit Arduinos
• 4.2.1.1: Using with TWELITE SPOT
• 4.2.1.2: Using with Arduino UNO R4
• 4.2.1.3: Extending Packet Parsers
• 5: Miscellaneous
• 5.1: TWELITE PAL/CUE/ARIA Script
• 5.1.1: How to Use
• 5.1.2: Source Files
• 5.1.2.1: PAL_Script.py
• 5.1.2.2: Main_user.py
• 5.1.2.3: MNLib
• 5.1.2.3.1: apppal.py
• 5.1.2.3.2: appbase.py
• 5.1.2.3.3: mwSerial.py
• 5.1.2.3.4: parseFmt.py parseFmt_*.py
• 5.2: TWE Programmer

1 - TWELITE STAGE SDK

1.1 - Installation Method

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.

Installation Procedure for TWELITE STAGE SDK

① Obtain the Archive

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

brew install twelite-stage

② Extract the Archive

Extract the downloaded Zip archive.

③ Check the Files

Check the extracted folder.

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.1.1 - Folder Structure

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

Folder search order

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

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

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.

1.1.2 - Platform-specific Notes

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

1.1.2.1 - Notes When Installing on 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.

1.1.2.2 - Notes When Installing on 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

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.

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.

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

1.1.2.3 - Notes When Installing on Linux

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.

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

Register the application according to your desktop environment as needed.

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.

1.1.2.4 - Notes When Installing on Raspberry Pi

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.

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.

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

Raspberry Pi OS (bookworm)

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

sudo apt update
sudo apt install raspberrypi-ui-mods

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

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

1.2 - TWELITE STAGE APP

1.2.1 - TWELITE STAGE APP Manual

It operates on various platforms:

• Windows 10
• macOS (High Sierra or later, supports both Intel and Apple Silicon Macs)
• Linux (Ubuntu 18.04)
• Raspberry Pi (Raspberry Pi 3 Model B, LCD Touch Screen, Raspberry Pi OS August 2020)
• (M5stack: Supported up to version 1.0. Versions 1.3 and later are not supported at the source level.)

※ Depending on the platform, operating conditions, distribution formats, and features may differ.

About this Document

• To indicate the target platforms, some pages specify the following:
  • Windows   – Windows 10
  • macOS   – Mac OS X, OS X, macOS
  • Linux   – Ubuntu, etc. (64bit)
  • RasPi   – Raspberry Pi

1.2.1.1 - Obtaining the Package

The latest TWELITE STAGE app can be obtained by one of the following methods.

Entire TWELITE STAGE SDK (Official Website)

The Mono Wireless official website distributes a complete set of development tools (for Windows/macOS/Linux), including the TWELITE STAGE app.

TWELITE STAGE-トワイライトステージ - MONO-WIRELESS.COM

TWELITE STAGE App Only (GitHub)

The Mono Wireless official repository distributes the standalone binary of the TWELITE STAGE app. Please use this if you want to update only the TWELITE STAGE app or obtain the M5Stack version. The version of each binary can be identified from the tags on GitHub.

Windows

monowireless/TWELITE_Stage_BIN_Win: Binary Distribution of TWELITE Stage.

macOS

monowireless/TWELITE_Stage_BIN_macOS: Binary distribution of TWELITE Stage for macOS

Linux

Linux binaries are not distributed separately. Please obtain binaries from the TWELITE STAGE SDK package or build from source code.

Raspberry Pi

Raspberry Pi binaries are not distributed separately. Please obtain binaries from the TWELITE STAGE SDK package or build from source code.

M5Stack

Versions up to 1.0.3a are distributed on the following page.

monowireless/TWELITE_STAGE_Bin_M5Stack

Source Code (MWM5 Library)

The MWM5 library, including the source code of TWELITE STAGE, is published on the following page.

monowireless/mwm5

The source code of the TWELITE STAGE app is placed in examples/TWELITE_Stage.

1.2.1.2 - How to Use

How to Launch the App

To launch the TWELITE STAGE app, execute the executable file located in {MWSTAGE Installation}.

The method of execution varies depending on the platform (Windows, macOS, Linux).

Executable Types of the App

The TWELITE STAGE APP has two types of executables.

• TWELITE_Stage.{extension} - Launches with standard settings.
• TWELITE_Stage_VSCode.{extension} - Configured to “Use VSCode” (settings saved in TWELITE_Stage_VSCode.ini). When the VSCode usage setting is enabled, the app operates in a way suitable for development work using VSCode.

App Interface

When you launch the app, two types of windows are displayed:

• Main Window
  • Displays the user interface of the TWELITE STAGE APP.
    • The serial port under connection (e.g. TWELITE-R or TWELITE STICK) is displayed in the title bar.
  • All operations of the TWELITE STAGE APP are performed within this window.
    • Press the ALT (Cmd) key to display the operating aid screen.
    • The [ A ] [ B ] [ C ] buttons appear at the bottom of the screen and are used for operation. These buttons can be pressed and held down to call up sub-functions.
• Command Window
  • Usually not used, but displays auxiliary information.
    • Shows serial communication content, making it ideal for checking logs.
    • When launched from the command line, the originating terminal acts as the command window.

Exiting the App

Exit the app by any of the following methods:

• Move the mouse pointer to the upper right of the execution screen and press the exit button displayed within the screen.
• Close the app window (on macOS, ⌘Q can also be used).

1.2.1.2.1 - Key and Mouse Operations

Windows   macOS   Linux   RasPi

Key Operations

Windows   macOS   Linux   RasPi

Key inputs performed while holding down Alt (Cmd) are assigned to operations such as changing the settings of TWELITE STAGE APP. Other key operations generally function as normal text input.

Common Keys

Windows   macOS   Linux   RasPi

Help Screen

Windows   macOS   Linux   RasPi

Hold down Alt (Cmd) to display the help screen. The help screen shows explanations of keys that can be used together with Alt (Cmd) and some operational status.

The help screen can also be displayed by moving the mouse pointer to the top-left corner of the screen.

Alt (Cmd) + Operations

Windows   macOS   Linux   RasPi

This section explains operations performed while holding down Alt (Cmd).

In the table below, the Alt (Cmd)+ prefix is omitted. You can check the available keys from the help screen above, but supplementary explanations are provided in the table below.

Other Operations

Mouse Operations

Windows   macOS   Linux   RasPi

Mouse operations mainly involve left-clicking, but right-click, right double-click, and the scroll wheel may be used.

Mouse Control of A, B, C Buttons

Windows   macOS   Linux   RasPi

When you move the mouse pointer to the menu display at the bottom of the screen, buttons labeled [ A ], [ B ], and [ C ] appear. TWELITE STAGE APP assigns functions of the hardware buttons arranged in this way to each screen. You can call the functions by left-clicking or long-pressing these buttons. (They can also be selected with Alt (Cmd)+a,s,d or Alt (Cmd)+Shift+a,s,d)

Mouse Control of Screen Operations

Windows   macOS   Linux   RasPi

On Windows/macOS/Linux, TWELITE STAGE APP screens are basically composed of text only, but menus, buttons, and tabs can be operated with the mouse.

The screen consists of text only, but the tabs at the top of the screen and inverted text can be selected by left-clicking with the mouse.

1.2.1.2.2 - Screen Operations

Windows   macOS   Linux   RasPi

Windows / macOS / Linux / Raspberry Pi

TWELITE STAGE APP is an application launched from the console screen (command line). It outputs information to both the console screen and window screen.

The console screen displays UART output similar to a terminal.

Raspberry Pi (nox)

Displays on the framebuffer without using X11.

Normally (when started from a shell screen on the framebuffer), the console screen is not displayed.

1.2.1.2.2.1 - Serial Port Selection

Windows   macOS   Linux   RasPi

Overview

On Windows / macOS / Linux, a screen to select the serial port connected to TWELITE is displayed at startup. However, the serial port can also be connected later.

Windows

Press the c key to display the COM port name of the serial port currently highlighted in the list.

Raspberry Pi

On Raspberry Pi, in addition to USB devices, if /dev/serial0 and /dev/serial1 exist, serial0 and serial1 will be displayed. Normally, serial0 is used.

1.2.1.2.2.2 - Main Menu

Windows   macOS   Linux   RasPi

This is the top level of the hierarchical menu.

On this screen, you select a menu. When a menu is highlighted, a brief explanation is displayed in green text at the bottom.

• Viewer: A viewer that interprets and displays packets received from TWELITE. In many cases, the receiving TWELITE is programmed with App_Wings.
• Write Firmware: Build the firmware and write it to the connected TWELITE.
• Interactive settigns mode: Configure the connected TWELITE settings via interactive mode.
• Settings of TWELITE STAGE: Configure various settings of the TWELITE STAGE app.
• Select SERIAL port: Select the serial port.
• Open MANUAL: Menu to display manuals. Opens the following manuals in a browser:
  • TWELITE STAGE App (this document)
  • MWX Library
  • TWENET_C Library

1.2.1.2.2.2.1 - Viewer

Windows   macOS   Linux   RasPi

The viewer is a feature for displaying information received from a connected TWELITE and sending commands.

1.2.1.2.2.2.1.1 - Terminal

Windows   macOS   Linux   RasPi

Overview

A general VT100-compatible serial terminal.

Supports TWELITE interactive mode and reset control.

Operations

1.2.1.2.2.2.1.2 - Standard App Viewer

Windows   macOS   Linux   RasPi

Overview

The TWELITE communicating partner should have App_Twelite (Standard App) programmed. When a message indicating the status of buttons or analog inputs of the Standard App (0x81 message) is received, its contents are interpreted and displayed using the mwm5 parser library.

Operations

1.2.1.2.2.2.1.3 - Graph

• Accelerometer Real-Time Graph: Displays accelerometer sensor packets in real time. Frequency domain display and CSV file saving are available.
• Sensor Graph: Saves data from various TWELITE sensors into an sqlite3 database and displays graphs.

1.2.1.2.2.2.1.3.1 - Accelerometer Real-Time Graph

Windows   macOS   Linux   RasPi

Overview

This refers to packets received from TWELITE CUE and TWELITE Motion Sensor PAL. It can display accelerometer data in real-time, and includes features for frequency analysis and CSV export.

It supports three modes: CUE mode, MOT mode, and 2525 FIFO mode.

When a continuous series of samples reaches a certain number (analysis window), frequency analysis of the XYZ axes is displayed. However, in 2525 FIFO mode, it is assumed to be always continuous.

When packet boundaries are explicit (e.g., when more than 3 seconds have elapsed since the previous packet, in CUE mode for each packet, or in MOT mode when the packet sequence number is discontinuous), four dummy samples are inserted and a pink background is shown.

Data from up to four nodes are stored on a first-come, first-served basis.

Operation

Sample Rate Estimation

The sampling rate is calculated from the packet reception times. It averages the reception times of multiple past samples to estimate one sample interval, so packet drops may cause significant errors. Also, the related log timestamp (T_SMPL) is an estimated value and is delayed compared to the packet acquisition time. Once sample rate estimation completes, graph scrolling becomes smooth.

Opening the CUE Graph Mode on Startup

Specify 31 in [STAGE Common Settings → Startup App Selection].

Log Output (Save Display Data)

Pressing the (c) Save Display Data button outputs up to 512 samples starting from the current display position (rightmost sample).

Log file name is {log folder}/acc_snap_{timestamp}.csv.

• Data has the newest sample at the right edge as sample number 512 (file end).
• When frequency analysis is performed, the last samples used for frequency analysis are included.
• Frequency analysis results are added to rows containing frequency analysis target samples (for 64 samples, results appear from sample 449 for 32 rows, showing from DC to high frequency components).

Additional Information

Log Output (Auto Save)

When the Accelerometer Real-Time Graph screen is opened and data is input, log files are automatically saved.

Log file name is log folder/accel_{serial number}_{timestamp}.csv.

Additional Information

1.2.1.2.2.2.1.3.2 - Sensor Graph

Windows   macOS   Linux   RasPi

Overview

Various sensor data are recorded in an SQLite database and displayed on the screen in graph format. The database file can also be accessed by external applications.

• The database uses SQLite (sqlite3) and is stored in the file {MW_STAGE Install}/log/{executable_name}_WSns.sqlite.
• Screen navigation is [List (with graph preview)] > [24-hour Data] > [Live View].
  • From [24-hour Data], you can further navigate to [Year], [Month], and [Day (with graph preview)] selection screens.
• About the [Live] display screen:
  • Select a specific node from the list.
  • Displays real-time data every second, showing data from the past 450 seconds.
• About the [24-hour Data] display screen:
  • Displays data for a specific day.
  • Updates every second; if multiple data points occur during that time, some are thinned out.
  • Except at maximum zoom (1 pixel = 1 second), the average value for the data within each pixel range is displayed.
  • If values exceed the screen, measurement points are shown at the top or bottom edges.
  • If the current time is included, the display updates with new data.
  • Mouse wheel or cursor keys ↑ and ↓: zoom in/out on the time axis.
  • Moving the mouse pointer: briefly displays the data corresponding to the time under the pointer.
    • Cursor keys → and ←: move to the adjacent data point.
  • Mouse click & drag: scroll (only when zoomed).
  • When zoomed, scrollbar operation is also possible.
  • The [CSV Export] function outputs all data in the database.

Operations

Editing Sensor Node Notes (Supplementary Information)

In the “24-hour Data” screen, left-clicking on the sensor node’s note area at the top right of the screen allows you to edit the note using a prompt.

Screen Navigation

The basic screens are divided into three types: List, 24-hour, and Live.

[List] <--> [24-hour] <--> [Live]
              ↓↑
          [Year/Month/Day Selection]

Starting Sensor Graph Mode on Launch

Specify 32 in [STAGE Common Settings → Launch App Specification].

About the Database Tables

sensor_data

Stores received data.

sensor_node

Stores text notes (supplementary information) for sensor nodes.

sensor_last

Manages the timestamp of the last received data.

1.2.1.2.2.2.1.4 - Simple Monitor

• CUE Viewer: Interprets packets from TWELITE CUE and displays them simply
• ARIA Viewer: Interprets packets from TWELITE ARIA and displays them simply
• Glancer: A simple monitor supporting many formats of TWELITE

1.2.1.2.2.2.1.4.1 - CUE Viewer

Windows   macOS   Linux   RasPi

Overview

Interprets and displays messages received from TWELITE CUE.

Operation of TWELITE CUE

The factory default setting of TWELITE CUE is configured to CUE mode.

In CUE mode, it operates intermittently to enable coin cell battery operation, waking from sleep due to several factors and transmitting various data.

Wake-up Factors

TWELITE CUE requires one of the following factors to wake from sleep:

• Wake-up by timer (periodic wake-up)
• Wake-up by acceleration detection
• Wake-up by magnetic sensor (when a magnet is detected nearby)

Types of Data Transmitted

TWELITE CUE sends the following data in packets:

• Detection events (see below)
• Module power voltage
• Magnetic sensor detection value
• Acceleration data

Packet Attributes

The attributes of received packets provide basic information.

Events

In CUE mode, acceleration events are always output. Regardless of the wake-up factor, a fixed number of acceleration samples are measured after waking. Events are determined based on the acceleration measurement results.

Voltage

Power supply voltage of the module [mV].

Magnet

Displays the detected magnetic pole or no detection.

Acceleration

Displays acceleration measured after waking.

• Samples: Displays the number of acceleration samples, fixed at 10 samples.
• Rate ID: Sample rate of acceleration, fixed at 04 (100Hz).
• X, Y, Z: Acceleration on three axes. Calculated as the average of 8 samples. Unit is milli-G (1000mG = 1G = 9.8m/s²).

Example Screens

1.2.1.2.2.2.1.4.2 - ARIA Viewer

Windows   macOS   Linux   RasPi

Overview

Interprets and displays messages received from TWELITE ARIA.

Operation of TWELITE ARIA

The factory default setting of TWELITE ARIA is TWELITE ARIA mode.

In TWELITE ARIA mode, it operates intermittently to allow coin battery power, waking from sleep due to several factors, and sending various data.

Wake-up Factors

TWELITE ARIA requires one of the following factors to wake from sleep:

• Wake-up by timer (periodic wake-up)
• Wake-up by magnetic sensor (when a magnet is detected nearby)

Types of Data Sent

TWELITE ARIA sends the following data packed in a packet:

• Module power supply voltage
• Magnetic sensor detection value
• Temperature and humidity data

Packet Attributes

Basic information can be obtained from the attributes of the received packet.

Temperature and Humidity Data Table

Displays the history of the last 9 data packets received from TWELITE ARIA. The latest data is displayed at the top.

Time [s]

Time [seconds] from when the TWELITE STAGE APP started until the data was received.

ID

Logical device ID of the module.

VCC (mV)

Power supply voltage of the module [mV].

Temperature (°C)

Temperature measured by the module (°C).

Humidity (%)

Humidity measured by the module (%).

Magnet

Displays the detected magnetic pole or no detection.

1.2.1.2.2.2.1.4.3 - Glancer

Windows   macOS   Linux   RasPi

Overview

Glancer provides a simplified display of the information contained in received messages.

By programming the connected TWELITE with App_Wings, it can display information received from communication partners’ TWELITE devices (App_Twelite, TWELITE PAL, … as long as the application ID and frequency channel match, mixed operation is possible).

Operation

Use by switching between the list display screen and the selection display screen.

List Display

Lists information from communication partners.

Displayed content includes message type, logical device ID, serial ID, LQI (Lq), power voltage (if included in the information), and timestamp.

Selection Display

By moving items and highlighting one in the list display, then performing a selection operation, you transition to this screen. It shows information related to a specific communication partner in order of arrival.

The number of received packets and the average LQI since selection are displayed.

1.2.1.2.2.2.1.5 - Commander

Windows   macOS   Linux   RasPi

Overview

Commander is a feature to send serial messages to TWELITE.

Operation

The first screen of the Commander displays important notes.

At the top of the screen, there are tabs represented by text, which you can navigate by clicking with the mouse to switch between tab screens.

Tab: TWELITE

This screen generates and sends the 0x80 command of the Standard App (App_Twelite).

Make sure the connected TWELITE has App_Twelite or parent/relay app (App_Wings) programmed, and after setting the application ID and channel, confirm that messages are being received from the communication partner.

Tab: NOTICE

This screen generates the LED control command of the Notification PAL (NOTICE PAL).

Make sure the connected TWELITE has App_Wings programmed, and after setting the application ID and channel, confirm that messages are being received from the communication partner.

Display at the bottom of the screen

At the bottom of the screen, the timestamp when the command was generated and the command starting with : are displayed. The clipboard copies the contents of this screen.

1.2.1.2.2.2.2 - Write App Firmware

Windows   macOS   Linux   RasPi

The firmware writing function allows you to write the TWELITE app (firmware).

• Write pre-built .BIN files
• Build from source files such as act and write

It eliminates the hassle of building source files, terminal disconnection, launching the writing utility, and terminal connection.

• Automatically recognize TWELITE
• After writing is complete, reset and then transition to interactive mode or terminal
• From the list of projects, launch the project folder or environments like VSCode (except Raspberry Pi version)
• From the list of projects, open related information web pages (except Linux and Raspberry Pi versions)

1.2.1.2.2.2.2.1 - Select from BIN

Windows   macOS   Linux   RasPi

Overview

You can write pre-built applications ( .BIN files ).

When you select the menu, a list of .BIN files will be displayed. Please select the firmware to write.

If you want to use a file other than the pre-prepared .BIN files, please store the file to be written in the following location before selecting the menu.

In the BIN folder, please store .BIN files built with TWELITE STAGE without renaming the files (they are stored under the build folder of each project).

../BIN/App_Wings_MONOSTICK_BLUE_L1304_V1-1-3.bin
       App_Wings_MONOSTICK_RED_L1304_V1-1-3.bin
       App_Twelite_BLUE_L1304_V1-9-1.bin
       App_Twelite_RED_L1304_V1-9-1.bin
       ...

1.2.1.2.2.2.2.2 - act Build & Write

Windows   macOS   Linux   RasPi

Overview

You can build and rewrite acts (act) written with the MWX library.

This screen displays a list of projects using acts placed in the following path.

{MWSTAGE installation folder}/MWSTAGE/Act_samples

Operation

You can build and write by selecting the project to write from the list.

After writing is finished, pressing ENTER or the [ B ] button will reset the TWELITE and transition to the interactive mode screen (or terminal screen, depending on settings).

Build and Write Screen

1.2.1.2.2.2.2.3 - TWELITE APPS Build & Write

Windows   macOS   Linux   RasPi

Overview

You can build and write TWELITE APPS written with the TWENET C library.

This screen displays a list of projects located in the following path:

{MWSTAGE installation folder}/MWSTAGE/Wks_TweApps

Operation

By selecting the project to write from the list, you can perform build and write operations.

After writing is completed, pressing ENTER or the [ B ] button will reset the TWELITE and transition to the interactive mode screen (or terminal screen, depending on settings).

Build and Write Screen

1.2.1.2.2.2.2.4 - Act_extras

Windows   macOS   Linux   RasPi

Overview

You can build and rewrite acts written with the MWX library.

This screen displays a list of projects using acts placed in the following path:

{MWSTAGE installation folder}/MWSTAGE/Act_extras

Operation

By selecting a project to write from the list, you can perform build and write operations.

After writing is complete, pressing ENTER or the [ B ] button will reset the TWELITE and transition to the interactive mode screen (or terminal screen, depending on settings).

Build and write screen

1.2.1.2.2.2.2.5 - Folder (Specify)

Windows   macOS   Linux  

By dragging and dropping a folder or .BIN file onto the TWELITE STAGE APP screen, you can write a specific project. Select the dropped target when performing build or write operations.

1.2.1.2.2.2.2.6 - Last (Re-execute)

Windows   macOS   Linux   RasPi  

Re-select the most recently rewritten or specified project.

1.2.1.2.2.2.2.7 - Build & Write Screen

Windows   macOS   Linux   RasPi  

During Build

This is the screen during the build (compile) process. The contents of the build command are output to the console screen. The ... in the middle of the screen indicates the number of files built, and the dark-colored display at the bottom shows the filenames currently being built.

Build Error

If a build error occurs, a screen like the one above is displayed. You can execute a rebuild or display the error log. Also, after a certain timeout, it will return to the previous menu.

Only representative error messages are displayed on the screen. When the build fails, there may be cases where the error message is not displayed.

During Write

When the build succeeds, the screen to write the firmware is displayed.

Write Failure

If writing results in an error, a screen like the one below is displayed.

Write Complete

When writing completes successfully, a screen like the one below is displayed.

1.2.1.2.2.2.3 - Interactive Settings Mode

Windows   macOS   Linux   RasPi

Overview

From this screen, you can use the interactive mode of the connected TWELITE.

This screen behaves almost the same as a terminal, but adds functions specific to interactive mode, such as operations to transition to interactive mode and detection of exit from it.

• The connected TWELITE must have firmware compatible with interactive mode pre-installed.
• Since TWELITE input/output is used, if garbled characters occur in serial communication, transitions to and exits from interactive mode may not work as expected.
• Mouse operations are not supported. Please use keyboard operations (cursor ↑ ↓ keys are usable).

Interactive Mode Screen Operation Flow

Below is an outline of the process flow.

[Set screen background to black]
  ↓
[Reset TWELITE (if controllable, SET=LO)]
  ↓
 --YES--> [Operation screen]
  ↓timeout
[Input '+' three times]
  ↓
 --YES--> [Operation screen]
  ↓timeout
[Operation screen] ※ This state is not interactive mode

[Operation screen]
  ↓
 --> [Exit]
  ↓
 --> [Exit]
  ↓
 ->  --NO-> [Exit]
  ↓            ↓
[Send input string to TWELITE]
  ↓
[Return to operation screen]

[Exit]
  ↓
[Reset TWELITE]
  ↓
[Exit screen] Exit the interactive mode screen and return to the previous screen

1.2.1.2.2.2.4 - Settings of TWELITE STAGE

Windows   macOS   Linux   RasPi

Overview

From this screen, you can configure various settings of the TWELITE STAGE APP.

Some menu items explained below may not exist on certain platforms, but all are listed and explained.

Color settings other than the common menu are omitted from the explanation.

Root Menu

Common
 Terminal
 Standard App Viewer
 Graph Viewer (Acceleration Real-time/Sensors)
 Simple Monitor (CUA/ARIA/Glancer)
 Commander
 Write firmware
 Interactive Settings Mode
Save Data Utilities (Dump/Erase)
Information

Common Settings

a: (      0x00) Startup App Specification
G: (      0x00) Screen Size and Drawing Method
F: (          ) Serial Device ID
f: (0x00FFFFFF) Foreground (Text) Color
b: (0x005A0032) Background Color
B: (    115200) Baud Rate

Write Firmware

f: (0x00FFFFFF) Foreground (Text) Color
b: (0x005A0032) Background Color
j: (         0) Number of make jobs at build time
v: (         0) Open a folder with VSCode
l: (         0) Disable LTO
n: (         0) Screen after rewriting is completed

Save Data Utilities

r: Read sector.
R: Read ALL sectors.
e: Erase sector.
E: Erase ALL sectors.

This screen is a utility for maintaining data save areas. It emulates EEPROM (64 bytes per sector, up to 60 sectors, 3840 bytes).

1.2.1.2.2.2.5 - Select SERIAL port

Windows   macOS   Linux   RasPi

Overview

On this screen, you can (re)select the serial port.

1.2.1.2.3 - Logging Function

Windows   macOS   Linux   RasPi

Operation

Start Recording

Press Alt(Cmd)+L.

Stop Recording

While recording, press Alt(Cmd)+L again.

The log recording will stop, and the log file at that point will be opened using the OS default application (Notepad on Windows, Console.app on macOS).

Specifications

Log Recording

Strings received from TWELITE are recorded as-is.

Strings sent to TWELITE are recorded one character at a time. On Windows, they are enclosed in ｢ ｣, and on macOS / Linux / Raspberry Pi, they are enclosed in « ». For example, «t» means that the character t was input from the keyboard.

Log Folder and File Name

Logs are saved in the {folder where the TWELITE STAGE APP executable is located}/log folder, with a file name based on the start date and time of the logging.

Press Alt(Cmd)+Shift+L to open that folder.

1.2.1.3 - Detailed Specifications

1.2.1.3.1 - Detailed Settings with Command-line Arguments and ini Files

Command-line Arguments

Command-line arguments configure some detailed settings of the TWELITE STAGE APP.

ini Files

ini files are used to configure basic settings of the TWELITE STAGE APP (such as referencing the MWSDK folder).

The ini file name is {base name of the TWELITE STAGE APP executable} + .ini. Usually, it is TWELITE_Stage.ini.

;;; Change the MWSDK reference.
; MWSDK=MWSDK
mwsdk=mwsdk2020_10

;;; Interface language
; LANG=en

;;; Window geometry
GEOM_X=200
GEOM_Y=100

Syntax

• ini files are written as plain text files.
• Keys and values are stored on a single line separated by = (e.g., KEY=value).
• The key and value strings start at the beginning of the line (no spaces or other characters allowed before the key).
• Spaces are not allowed between the key and the value.
• Comment lines start with ; or # at the beginning of the line.

Settings

Running TWELITE STAGE APP with Different Settings

If you need different settings for the TWELITE STAGE APP, copy the executable to the same folder as the TWELITE STAGE APP and create an .ini file with the same name.

For example, to use the English interface, copy TWELITE_Stage.exe (note: .exe is the Windows executable extension) to TWELITE_Stage_en.exe and write the setting LANG=en in TWELITE_Stage_en.ini to create an executable with the English interface enabled.

  TWELITE_Stage.exe
  TWELITE_Stage.ini | No special settings

  TWELITE_Stage_ja.exe | Copy of TWELITE_Stage.exe
  TWELITE_Stage_en.ini | LANG=en is set.

1.2.1.3.2 - Environment Variables

Environment Variables Set Internally

Reference

Excerpt from .vscode/settings.json configuration example:

    "C_Cpp.default.includePath": [
        "${env:MWSDK_TWENET_LIBSRC}/include/**",
        "${env:MWSDK_TWENET_LIBSRC}/src/**"
    ],
    "C_Cpp.default.browse.path": [
        "${env:MWSDK_TWENET_LIBSRC}/include/**",
        "${env:MWSDK_TWENET_LIBSRC}/src/**"
    ],

Definitions starting with "../../" are unnecessary when opening a project from the TWELITE STAGE app. These specify source reference paths in the default folder structure when the environment variable MWSDK_TWENET_LIBSRC is not set.

1.2.1.3.3 - Adding Project Descriptions with 000desc.txt

When you create a 000desc.txt file in the project folder, TWELITE STAGE APP displays its contents in the project folder list.

The file should be written as plain text in UTF-8 format. There are two formats as follows.

Format 1

LED lights up when the switch is pressed
act4 operates an act that lights up the LED when the switch connected to TWELITE DIP is pressed.
https://mono-wireless.com/jp/products/act/index.html

• The first line is the title line.
• The following lines describe details.
• If the last line starts with http, it becomes a link to a website.

Format 2

[JAPANESE]
TITLE=act template
DESC=This file contains only empty setup() and loop() functions.
Please use it to write a new act.
URL=jp/MWX/content/Act_samples/README.html
[ENGLISH]
TITLE=act empty template
DESC=This act file only contains empty setup() and loop(),
which is intended to write a new act.
URL=en/MWX/content/Act_samples/README.html

This format is like an ini file. The item name starting from the beginning of the line and the = character define the item, and the content after = is the item’s content.

About URL specification

1.2.1.4 - License

The executable format of TWELITE_Stage distributed by Mono Wireless Inc. is subject to MW-SLA-1J,1E.

Open Source Components Used

We appreciate the open source projects that provided high-quality source code.

1.2.1.5 - Revision History

Please refer to https://github.com/monowireless/mwm5 for the source code change history.

• Depending on the platform, the latest version distributed and the latest version in the revision history may not match.
• The latest version of the source code may not be registered at the above sites.

2.4.4 MWSTAGE2025_07 Release

Major Version Upgrade

• Added support for TWELITE STICK
• Enhanced serial port functionality
  • Added baud rate switching via ALT+B
  • Connection status now displayed in the title bar
• Makefile error message handling
  • Extracts the message part ... from errors output in the format $(error <MWERRM>...</MWERRM>)
  • These error messages are intended to be used when attempting to build projects for unsupported architectures (e.g., GOLD only, or BLUE/RED only)
• Support for language setting in interactive mode
  • Interactive mode language can now be specified at build time via TWE_LANG_PREF=(JP|EN)
  • When launching external tools (e.g., VSCode), the MWSDK_MAKE_LANG_PREF environment variable is now set

2.4.3

• For projects with multiple configuration types located in subfolders (and not directly under the root build), folder listing is now limited to only those that contain a build/ directory, preventing unnecessary folders from being shown
• Fixed a crash that occurred when error messages were too long during build errors
• Changed the order of serial protocol checks for determining BLUE/RED/GOLD: now tries GOLD first (for GOLD-targeted SDK)

2.4.2

• Added support for interactive mode transition control using the SET pin (CTS pin on MONOSTICK)
  • Behavior in TWELITE_Apps is as follows:
    • If SET pin is held for less than ~100ms → normal boot (prevents accidental interactive mode entry due to noise)
    • If held longer than the above → enter interactive mode on boot
    • If held for ~3 seconds or more → erase entire EEPROM on startup
    • Each app is informed of the interactive mode transition via a startup parameter
      • Apps receiving this parameter will, in principle:
        • Skip app-specific initialization
        • Skip interrupt handler setup, etc.
        • Automatically start interactive mode on UART0 at 115200 8N1
        • Suppress exit from interactive mode via +++
  • Under this spec, the STAGE app behaves as follows:
    • For regular transition to interactive mode, hold the SET pin for about 300ms
      • When holding [ C ] on the interactive mode guidance screen, SET pin is held for about 5 seconds
      • If Entering Interactive ... message is not received within timeout, fallback to trying +++ as per previous behavior
• Additional code cleanup

2.4.1

• Initial support for TWELITE GOLD
  • If a control command response from GOLD is received at startup, it’s recognized as GOLD; if it fails, control commands for the BLUE/RED series are attempted instead

1.3.8 MWSTAGE2022_08 Included Version

Major version upgrade.

• Changed internal rendering resolution from 320x240 to 640x480 pixels
• Added real-time graph for accelerometer sensor
• Added sensor graph that saves sensor data and displays graphs
• Supported English display
• Changed main manuals to local HTML files

1.0.8 MWSTAGE2021_09 Included Version

• There was a case where buttons [ A ] [ B ] [ C ] remained pressed even after the pointer moved away
• STAGE APP sends CRLF to TWELITE when Enter is input
• Updated Mac FTDI library to allow operation without serial intermediary program on Apple Silicon (M1)
• Internally set PATH for msys toolset on Windows to prevent unexpected make calls
• Allowed moving to the writing screen even if TWELITE is not connected (input B,R keys and specify the target TWELITE model)
• When configured to use VSCode, selecting act or TweApps opens the writing screen for .bin files under build/ without building (build is done from VSCode)
• Internally set several environment variables so that VSCode launched from TWELITE STAGE can refer to them, enabling proper builds and library resource referencing in VSCode
• Sample code is stored under MWSDK folder, but dropping a folder for build target allows build and write operations for folders other than MWSDK (folder names must not contain spaces or Japanese characters)
• Displayed internal folder settings and environment variable settings on the console screen at startup
• Waited 1 second before exiting STAGE APP on termination

1.0.7pre2

• Enhanced support for Raspberry Pi (1.0.7pre2)
  • Support for serial0 (TWELITE STAGE HAT)
  • Added build for Zero (build with supported libraries & disabled rendering fade feature)
  • Added build for X11 desktop
• Made it usable with general FTDI devices (FT232, FT230). Firmware writing mode must be done manually
• Added feature to display COM ports assigned in Windows by pressing c key on serial port selection screen
• Allowed changing baud rate from 115200bps
• Added command line option (-E 0) to disable rendering fade feature.

1.0.3 MWSTAGE2020_12 Included Version

• Supported TWELITE CUE (parser and CUE viewer)
• Enabled verification (comparison) during writing in the rewrite menu
• Provisional support for Apple Silicon (TWELITE_Stage.command is a universal app; external command sersrv_ftdi.command and Tools are rebuilt Intel binaries runnable with Rosetta2; serial communication is slower due to external command)
• Moved MWSTAGE/MWSDK/Tools to MWSTAGE/Tools (to allow direct use of MWSDK_COMMON repository)
• TWELITE_Stage.ini (removes extension from startup filename and adds .ini) is loaded at startup to allow selecting MWSDK folder (makes it easy to switch old library sets)
• Updated SDL2 library for screen rendering to 2.0.12 (Windows, MacOS, RaspberryPi)
• Static build on Windows with no DLL files required
• Set parallel build count for make -j to (number of physical CPUs - 1)
• Explicitly reopened serial port in several places in rewrite menu to improve recovery when USB connection is disconnected due to device removal
• When opening mwx or twesettings with Alt(Cmd)+Shift+m, t, opens folders listed in TWENET/usever.mk
• Fixed issue where writing menu transition failed on first startup at /dev/serial0 on Raspberry Pi

Known Issues

• Help message when pressing Alt(Cmd) at startup may not appear; can be shown by inputting Alt(Cmd)+0
• Line wrapping may be broken when filenames are too long in rewrite menu
• Apple Silicon operation has not been sufficiently tested

0.9.11 MWSTAGE2020_10, Raspberry Pi Version (Provisional)

(* This version is not comprehensively tested *)

• Operation on Raspberry Pi
• Other feature adjustments

0.9.9 - MWSTAGE2020_10 Included Version

• Added [Web] button to the top-level menu to open related links in browser
• Implemented folder, web, and VS Code open features for Linux version
• Sometimes difficult to transition to writing menu when TWELITE frequently outputs UART

0.9.8a

https://github.com/monowireless/TWELITE_STAGE_Bin_M5Stack/releases/tag/0.9.8a

M5Stack version made dual-licensed for MW-SLA-1J,E / MW-OSSLA-1J,E and updated readme-j.txt.

0.9.8

Added [Web] button to viewer list to open related sites.

Revision Details

• Added Commander to viewer
  • Standard app 0x80 command
  • NOTICE PAL LED control (send commands to App_Wings)
• NOTICE PAL support for viewer > PAL viewer
• Added menu for Act_extras
  • More advanced than Act_samples
  • Uses external open source libraries (e.g. sensor procedures)
• Expanded mouse operation (lists, buttons, tabs)
  • Focus on mouse move, confirm with left click, right click inputs [ESC] key
• Reduced screen rendering load
  • Disabled screensaver when app is in background
  • Reduced rendering frequency when app is in background to lower CPU load
• Enhanced build project list (act, TWE_Apps, Act_extras)
  • Show summary at bottom when selecting items (reads 000desc.txt, processed by TWE_Desc class)
  • Ability to open project folder (or open in VSCode)
  • Ability to open related websites
  • Open mwx library with Alt+Shift+m and twesettings library with Alt+Shift+t
  • Open selected folder or build error files in build menu
• Added logging (serial port input/output)
  • Start/stop log with (Alt/Cmd+L)
  • Log files saved in {folder containing TWELITE_Stage executable}/log
  • Filename format: twestage_{date-time}.log
  • Open log file folder with Shift+Alt/Cmd+L
• Other changes and fixes
  • Changed display method for serial (FTDI) device names and IDs
  • Fixed issue where App_UART did not transition to interactive mode
  • Changed behavior on folder drop (previously sometimes triggered binary write, now transitions menu)
  • On terminal long press [C], clears screen in addition to reset

Known Issues

• M5Stack may hang and reset settings to default when saving settings

0.8.9

2020_05 Release Version

• Added window icon
• Relaxed maximum list constraints on BIN file list screen (win/linux/mac)
• Added Glancer viewer
• Adjusted explanatory text
• Adjusted console screen rendering
• Fixed issue where setting destination screen after firmware write (interactive mode or terminal) did not work
• Changed assignment of Alt(or Cmd)+W
• Other bug fixes

0.8.6

Initial release of Linux version

0.8.5

Initial release

1.3 - TWELITE APPS

What is Interactive Mode

Interactive mode is the mode to perform detailed settings of TWELITE APPS.

You can make necessary settings when you want to communicate with multiple groups or reduce communication errors.

Connection with PC

For TWELITE	For MONOSTICK
Attach the TWELITE R series to the 7P interface prepared on the parent board and connect to the PC using a USB cable.	Connect the MONOSTICK to the PC’s USB port. TWELITE R series is not required.

For TWELITE DIP (BLUE/RED)	For Others
Attach to TWELITE R series and connect to the PC using a USB cable.	For TWELITE series with 7P interface, attach TWELITE R series and connect to the PC using a USB cable.

Switching to Interactive Mode

When Using TWELITE STAGE

TWELITE STAGE APP is an integrated development tool that includes firmware writing and configuration of TWELITE, as well as a function to display received data.

1. Launch TWELITE STAGE APP

2. Select “Interactive Mode” from the menu of TWELITE STAGE APP

When Using Terminal Software

You can also use general terminal software.

1. Launch terminal software on the PC (communication settings: 115200bps/8-N-1)
2. Reset TWELITE.
3. Slowly press the + key on the PC keyboard three times (interval 0.2 to 1 second). If it does not work well, keep entering + repeatedly.

To exit interactive mode, press + three times again.

Operation of Interactive Mode

Interactive mode displays a screen like the following.

--- CONFIG/TWELITE APP V1-00-2/SID=0x81000038/LID=0x78 ---
 a: set Application ID (0x67720102)
 i: set Device ID (--)
 c: set Channels (18)
 t: set mode4 sleep dur (1000ms)
 y: set mode7 sleep dur (10s)
 f: set mode3 fps (32)
---
 S: save Configuration
 R: reset to Defaults

The displayed content varies depending on the firmware type and version.

Steps

1. Select value: press the first letter alphabet
2. Specify value: input the value
3. Confirm value: press Enter
4. Save value: press S (uppercase)
5. Apply value: restart TWELITE

Values in parentheses indicate the current setting.

Pressing R (uppercase) resets to default values (apply with S).

Example of Operation

To set the Application ID to 0xBEEFCAFE, input as follows:

Input Application ID (HEX:32bit): BEEFCAFE

Common Settings for TWELITE APPS

Frequency channel, application ID, device ID, retry count, and transmission output settings are common to TWELITE APPS.

Application ID and Frequency Channel

Devices must have the same application ID and frequency channel to communicate.

a: Application ID

Setting the same value to all devices communicating allows logical network separation.

TWELITE discards packets received from devices with different application IDs. Therefore, multiple groups can be established within the same frequency channel.

c: Frequency Channel

Setting the same value to all devices communicating allows physical network separation.

TWELITE conforms to the IEEE802.15.4 standard and divides the 2.4GHz band into 16 channels.

To change the frequency channel, press c (lowercase).

Use of Channel Agility (usually not recommended)

By specifying multiple channels separated by commas, channel agility can be enabled.

Channel agility improves communication success rate in poor communication environments by switching multiple frequency channels at regular intervals during communication.

Up to 3 channels can be specified simultaneously. The specified channels are switched in order at regular intervals for transmission. The receiver also switches channels in order at regular intervals for reception.

Reception is not possible during channel switching. In normal communication environments, reliability is lower than specifying a single channel. Since the number of transmissions from the child device needs to be increased, it is a wasteful method in terms of battery consumption. However, use it when you want to handle situations where certain channels become completely unusable. Normally, it is recommended to specify a single channel after identifying a channel with less interference in advance.

Default Values for Each TWELITE APP

i: Logical Device ID

The logical device ID is used to identify each device. You can assign logical IDs to each device.

When using multiple child devices for one parent device, assign different IDs (1 to 100) to each child device.

x: Transmission Output and Retry Count

You can weaken the transmission output to narrow the effective radio transmission range. However, power consumption does not change, so normally use the maximum output.

Retry count refers to the number of additional transmissions per one transmission request. Setting retry count may improve data arrival rate in poor communication environments. However, communication time and power consumption increase accordingly.

In interactive mode, input a two-digit number.

• Tens place: retry count
  • 1 to 9 times
  • 0 is the default value for each app
  • F disables retry
• Ones place: transmission output
  • 3 is the strongest
  • 2/1/0 each step down reduces output by -11.5dB

Examples

• 32 → Retry 3 times, output one level weaker
• 93 → Retry 9 times, maximum output

Resetting Settings

Some settings may interfere with operation (such as baud rate changes).

You can reset settings by the following steps.

1. Rewrite to another app
2. Switch to interactive mode
   • Reset with R
   • Save with S
3. Write back to the original app

App-specific Settings for Each TWELITE APP

For settings that differ between apps, please see the following pages.

1.3.1 - TWELITE APPS (Unified) Manual

1.3.1.1 - TWELITE APPS (Unified) Manual

Overview

The unified firmware bundles the following TWELITE APPS:

• Extremely Simple! Standard App (App_Twelite)
• Parent and Repeater App (App_Wings)
• Remote App (App_IO)
• Serial Communication App (App_Uart)
• CUE Setting App (App_CUE_OTA)
• ARIA Setting App (App_ARIA_OTA)

Switching involves a reset, but it can be performed from software without rewriting the firmware.

How to Switch

1. Open Interactive Mode

Access the Interactive Mode of TWELITE APPS and enter : (AppSel).

[CONFIG MENU/App_Wings:PARENT:0/v1-03-2/SID=8300051A]
a: (0x67720102) Application ID [HEX:32bit]
c: (18        ) Channel(s)
x: (      0x03) RF Power/Retransmissions [HEX:8bit]
b: (115200,8N1) UART Baud Alt. [XXXXX]
o: (0x00000000) Option bits [HEX:32bit]
t: (0xA5A5A5A5) Encryption key [HEX: 32bits]

[ESC]:Exit [!]:Reset System [*]:Extr Menu [:]:AppSel

2. Open the TWELITE APPS List

A menu like the following will display a list of TWELITE APPS:

[TWELITE AppSel/v0-02-1/SID=8300051A/SAVE=04-12-01]
M: AppSel           App selector (this screen)
R: Revert to DEFAULT(*DEF)
A: App_Twelite      Standar app. (App_Twelite)
B: App_IO           App for remote. (App_IO)
C: App_UART         App for SERIAL comm. (App_Uart)
D: App_Wings        Parent/Repeater (App_Wings)(*DEF)
E: App_OTA          OTA Apps for ARIA/CUE.

[!]:Reset [R]:Revert [$]:LANG=English

3. Select a TWELITE APP

Just like in Interactive Mode, you can switch to a TWELITE APP by entering the command ID letter.

For example, in the above example, entering C switches to App_Uart.

[App_UART / App for SERIAL comm. (App_Uart)]
Designed for UART (Serial) communications. UART is commonly used on MCUs.

=== Please select from the list below. Save the startup application. ===
1: Normal
2: for TWELITE UART

[BS]:Back

Initialize TWELITE APP

On the TWELITE APP list screen, entering R will revert to the default TWELITE APP.

! Clear Save Data? The next key will perform:
S: Clear App Selection.
!: Clear ALL SAVE DATA.

[BS]:Back

1.3.2 - Extremely Simple! Standard App Manual

1.3.2.1 - Extremely Simple! Standard App Manual

Download

To install the Extremely Simple! Standard App (App_Twelite), install the TWELITE STAGE SDK and rewrite using the TWELITE STAGE App.

1.3.2.1.1 - Pin Assignments of Extremely Simple! Standard App

Pin Assignments

Power Input

Connect a 3.3V (2.3-3.6V) power supply to VCC/GND.

Digital and Analog Input/Output

DIx/DOx, AIx/PWMx pins transmit signals synchronously with matching pin numbers.

Serial Communication

UART

TX/RX are used for UART transmission and reception. Specifically, they are used in the following cases:

• Wireless signal transmission
  • UART signal transmission
  • I2C signal transmission (on the parent device side)
• Wired communication with external devices
  • Output of data received wirelessly
  • Input of data to be sent wirelessly
• Firmware management
  • Firmware setting changes (Interactive Mode)
  • Firmware rewriting

I2C

SCL/SDA pins are used to connect I2C target devices.

Configuration Input

By leaving the Mx pins unconnected or connecting them to GND, you can switch operation modes such as parent, child, and repeater (Operation Modes).

By leaving the BPS pin unconnected or connecting it to GND, you can change the UART baud rate from 115200bps to other values (Alternative Baudrate).

Reset Input

By connecting a push button between the reset input pin RST and GND, you can implement a reset button. RST is internally pulled up.

1.3.2.1.2 - Operating Modes of Extremely Simple! Standard App

List of Operating Modes

Each mode is set by leaving the Mx pin unconnected or connecting it to GND.

O: Not connected (OPEN), G: Connected to GND

Initial state is Child: Continuous mode.

The initial Logical Device ID (LID) used to identify the device varies depending on the mode.

Parent Device

Continuous Mode

Parent: Continuous Mode

When input signals change or every 1 second, data is sent to all child devices.

It always waits for data sent from child devices, providing good responsiveness but continuously consuming power.

• Reception: Always waiting
• Transmission: On input change / every 1 second

Child Device

Continuous Mode

Child: Continuous Mode

When input signals change or every 1 second, data is sent to all parent devices.

It always waits for data sent from parent devices, providing good responsiveness but continuously consuming power.

• Reception: Always waiting
• Transmission: On input change / every 1 second

Child: Continuous 0.03s Mode

This mode shortens the periodic transmission interval of Child: Continuous Mode from 1 second to 0.03 seconds.

Although it always waits for data sent from the parent, the communication from child to parent occupies the bandwidth, making the parent’s input response slower. It continuously consumes power.

• Reception: Always waiting
• Transmission: On input change / every 0.03 seconds

Intermittent Mode

Child: Intermittent 1s Mode

When input signals change or every 1 second, power-saving mode is canceled and data is sent to all parent devices.

Reception is disabled, so control from the parent device is not possible. This mode has excellent power-saving performance.

• Reception: Disabled
• Transmission: On input change / every 1 second

Child: Intermittent 10s Mode

When input signals change or every 10 seconds, power-saving mode is canceled and data is sent to all parent devices.

Reception is disabled, so control from the parent device is not possible. This mode has excellent power-saving performance.

• Reception: Disabled
• Transmission: On input change / every 10 seconds

Child: Intermittent Reception 1s Mode

When input signals change or every 1 second, power-saving mode is canceled and data is sent to all parent devices.

Reception is also performed every 1 second. It has excellent power-saving performance but is inferior to Child: Intermittent 1s Mode.

• Reception: Every 1 second
• Transmission: On input change / every 1 second

Repeater

Continuous Mode

Repeater: Continuous Mode

The repeater forwards received packets.

Up to three repeaters can be installed between parent and child devices, but increasing repeaters increases the number of packets, which may cause interference.

• Reception: Always waiting
• Transmission: On reception

1.3.2.1.3 - Alternative Baud Rate Setting for Extremely Simple! Standard App

Enabling Alternative Baud Rate Setting

You can enable the alternative baud rate setting by connecting the BPS pin to GND.

O: Not connected (OPEN), G: Connected to GND

1.3.2.1.4 - UART Function of Extremely Simple! Standard App

Digital and Analog Input/Output

0x81: Status Notification from Remote Device

Outputs the state of the received input signals.

Data Format

Calculation of Analog Signals

The input voltage \(V\) of AIx can be expressed using the received conversion value \(e_{r}\) and correction value \(e_{fr}\) as follows:

Unit: mV

Example Output Data

:78811501C98201015A000391000C2E00810301FFFFFFFFFB

0x80: Remote Device Output Change

Controls the output signals of the remote device.

Data Format

UART Input/Output

0x01: Transmission of Arbitrary Data

Data Format

0x01: Reception of Arbitrary Data

Data Format

I2C Input/Output

0x88: I2C Input

Data Format

0x89: I2C Output

Data Format

1.3.2.1.5 - Interactive Mode (Extremely Simple! Standard App)

This section explains functions specific to the Extremely Simple! Standard App (App_Twelite). For common features, please refer to the TWELITE APPS manual top page.

Display Example

The following screen is displayed.

--- CONFIG/TWELITE APP V1-08-2/SID=0x8201001f/LID=0x78 ---
 a: set Application ID (0x67720102)
 i: set Device ID (--)
 c: set Channels (18)
 x: set Tx Power (03)
 t: set mode4 sleep dur (1000ms)
 y: set mode7 sleep dur (10s)
 f: set mode3 fps (32)
 z: set PWM HZ (1000,1000,1000,1000)
 o: set Option Bits (0x00000000)
 b: set UART baud (38400)
 p: set UART parity (N)
---
 S: save Configuration
 R: reset to Defaults

Commands

Details of each command are shown below.

a: Application ID

All devices communicating must share the same value. It logically separates networks.

i: Logical Device ID

Set when it is necessary to identify multiple child devices.

Set any value from 1 to 100 for child devices, 121 for parent devices, and 122 for relay devices.

c: Frequency Channel

All devices communicating must share the same value. It physically separates networks.

x: Transmission Output and Retry Count

Specify the radio transmission output and the number of additional packet transmissions.

t: Child Intermittent 1-second Mode Interval

Overrides the intermittent interval of the child intermittent 1-second mode from 1 second to another value. Unit is milliseconds.

Setting 0 disables periodic wakeup by timer. In this case, wakeup occurs on falling edge of DIx but not on rising edge.

y: Child Intermittent 10-second Mode Interval

Overrides the intermittent interval of the child intermittent 10-second mode from 10 seconds to another value. Unit is seconds.

Setting 0 disables periodic wakeup by timer. In this case, wakeup occurs on falling edge of DIx but not on rising edge.

f: Child Continuous 0.03-second Mode Cycle

Overrides the number of transmission requests per second from 32 times to 4/8/16 times. Retry count is not included.

z: PWMx Frequency

If one value is specified, it overrides the frequency of all PWM ports. If specified by comma separation, individual values for PWM1 to PWM4 can be overridden.

o: Option Bits

Specify a 32bit number. Enables settings linked to each bit.

b: UART Alternative Baud Rate

Overrides the alternative baud rate selected when the BPS pin is connected to GND at startup from 38400bps.

Values can be selected from 9600/19200/38400/57600/115200/230400. Specifying other values may cause errors.

p: UART Parity

N means no parity, O means odd parity, and E means even parity.

Data bits are fixed to 8, stop bits to 1. Hardware flow control cannot be set.

Details of Option Bits

Explanation of settings linked to each bit of the Option Bits value.

00000001: Low Latency Mode

Low Latency Mode shortens the delay on the receiver side by quickly transmitting after detecting changes in DIx.

00000002: Disable Periodic Transmission

Disables periodic transmission every 1 second in continuous mode for child devices.

00000004: Disable Periodic Transmission and UART Output

For child devices: disables periodic transmission every 1 second in continuous mode and stops UART output of received data.

00000010: Disable Transmission on AIx Change

For child devices: disables transmission when AIx input changes in continuous mode.

Since released AIx ports report undefined values, connect them to VCC when analog input is not used. This option allows omission of connection to VCC.

00000020: Disable AIx Value

Sends packets treating unused ports as 0xFFFF without using ADC measurement values.

00000040: Change PWMx Calculation Formula

By default, adjusted output for volume control is applied to PWMx.

This option disables that and outputs full scale for inputs below 1.8V.

00000100: Transmit Only When Button Pressed

Continuously transmits packets when DIx input is Low.

For example, used to remotely control a motor. The motor runs while the remote button is pressed and stops when the radio signal is lost.

00000800: Disable Internal Pull-up of DIx

Disables all internal pull-ups (about 50kΩ) of DIx.

00008000: Add Relay Function to Child

Adds relay function to child devices in continuous mode. Maximum relay steps is 1.

00001000: Set Max Relay Steps to 2 for Child Relay

Changes maximum relay steps to 2 when 00008000: Add Relay Function to Child is set.

00002000: Set Max Relay Steps to 3 for Child Relay

Changes maximum relay steps to 3 when 00008000: Add Relay Function to Child is set.

00010000: Invert PWMx Waveform

Inverts the output waveform of PWMx.

When maximum value is input to AIx, PWMx becomes Low.

00020000: Turn Off PWMx After Startup

Sets PWMx output to Low state after startup or reset.

00080000: Alternative Port Assignment

Enables alternative port assignment.

Connecting transistors etc. to PWM2/PWM3 may cause unstable operation (Details). Use this option in such cases.

00100000: Turn Off DOx for 2 Seconds After Startup

Sets DOx to Low state for 2 seconds after startup or reset.

You can light LEDs connected to DOx at startup.

00400000: Invert DOx Output

Inverts DOx output.

Unlike the initial state, when one DI is Low level, the other DO is High level.

00800000: Disable Internal Pull-up of DOx

Disables all internal pull-ups (about 50kΩ) of DOx.

1.3.3 - Parent and Repeater App Manual

1.3.3.1 - Parent and Repeater App Manual

Features

Can process all data packets of TWELITE APPS and act, and can be used as common parent or repeater.

• Collect data from multiple TWELITE APPS and act such as Extremely Simple! Standard App and Pal App with one MONOSTICK.
• Can operate multiple systems separately on 16 channels.
• By setting application ID, multiple systems can coexist on the same channel.
• Communication range extension with repeater function.

1.3.3.1.1 - Operating Modes of Parent and Repeater App

There are two modes: Parent mode and Repeater mode.

1.3.3.1.1.1 - Parent Mode of Parent and Repeater App

Receives data sent from child devices and outputs it via the serial port. Also sends commands input from the serial port to child devices.

1.3.3.1.1.1.1 - Messages of Parent and Repeater Apps

Receives data sent from child devices and outputs it from the serial port in a predefined format.

1.3.3.1.1.1.1.1 - Output from the Extremely Simple! Standard App (Parent and Repeater App)

0x81: Status Notification from the Peer Device

Outputs the status of the received input signals.

Data Format

Calculation of Analog Signals

The input voltage \(V\) of AIx can be expressed by the received converted value \(e_{r}\) and the correction value \(e_{fr}\) as follows:

The unit is mV

Example of Output Data

:78811501C98201015A000391000C2E00810301FFFFFFFFFB

Data Identification Conditions

The parent and relay apps can receive data from various types of child devices.

To confirm whether the output data is from the Extremely Simple! Standard App, refer to the following:

Parser Implementation Examples

• Python
  • mwings_python/src/mwings/parsers/app_twelite.py
• Arduino (C++)
  • mwings_arduino/src/parser/AppTwelitePacketParser.h
  • mwings_arduino/src/parser/AppTwelitePacketParser.cpp

0x01: Reception of Arbitrary Data

Data Format

1.3.3.1.1.1.1.2 - Output from Remote Control App (Parent and Repeater App)

0x81: Status Notification from Remote Device

Outputs the state of the received input signal.

Data Format

Example of Output Data

:01810F01DB8630000200645F000040004F00400049

Data Identification Conditions

Parent and Repeater App can receive data from various types of child devices.

To confirm that the output data is from the Remote Control App, refer to the following conditions.

Example Parser Implementations

• Python
  • mwings_python/src/mwings/parsers/app_io.py
• Arduino (C++)
  • mwings_arduino/src/parser/AppIoPacketParser.h
  • mwings_arduino/src/parser/AppIoPacketParser.cpp

1.3.3.1.1.1.1.3 - Output from Serial Communication App (Parent and Repeater App)

Format Mode: Simple Format

Data Format