Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Installing the TWELITE SDK
Download the TWELITE STAGE SDK distribution archive (e.g. ZIP) and extract it to an appropriate folder.
The folder names of each level of the destination folder must not contain anything other than one-byte numbers 0..9, one-byte alphabets a..zA..Z, and some symbols -_.. In short, it must not contain spaces, Kanji characters, Hiragana characters, etc.
The following is an example folder after extracting the TWELITE STAGE SDK archive. (Windows, c:\work\MWSTAGE...)
See Installing the TWELITE STAGE SDK for more information.
This is the end of the normal installation process. Refer to the following "Set Environmental variables" and below as necessary.
If you want to build with other than TWELITE STAGE application, please set the environment variables (e.g. MWSDK_ROOT).
If you are using the TWELITE STAGE application, you do not need to set these environment variables. Inside the TWELITE STAGE application, those environment variables will be set appropriately.
MWSDK_ROOT, MWSDK_ROOT_WINNAME(for Windows10) need to be set.
In this example, the name of the extracted folder is C:\MWSTAGE. If you have installed the software in a different folder, please change the name.
Run C:\MWSTAGE\Tools\SET_ENV.CMD to set the following environment variables:
MWSDK_ROOT
MWSDK_ROOT_WINNAME
For example, the following variables are set:
To uninstall the TWELITE STAGE SDK from the installed PC, please do the following:
Run UNSET_ENV.cmd. This will unset the environment variables.
Delete the MWSTAGE folder.
Set the development environment and shell to reflect the MWX_ROOT environment variable.
There are several ways to do this, but add the following setting to the .profile of your home folder (if the file does not exist, please create a new one). You can even build VSCode with this setting.
MWSDK_ROOT=/foo/bar/MWSTAGE/MWSDK/
export MWSDK_ROOT
To add it without using the editor, enter the command as follows. The $ is a prompt and will be displayed differently depending on your environment. The /foo/bar/MSWSDK part should be rewritten according to the installed folder.
Set the development environment and shell to reflect the MWX_ROOT environment variable.
There are several ways to do this, but add the following settings to .profile in your home folder (create a new file if you don't have one). You can even build VSCode with this setting.
MWSDK_ROOT=/foo/bar/MWSTAGE/MWSDK/
export MWSDK_ROOT
To add it without using the editor, enter the command as follows. The $ is a prompt and will be displayed differently depending on your environment. The /foo/bar/MSWSDK part should be rewritten according to the installed folder.
Use LaunchD to apply MWSDK_ROOT to the entire environment.
Some settings in VSCode refer to environment variables, but they are not required for the build.
DESC
In order to create a development environment, you need to install the software and agree to the license agreement. In addition, you may need to configure security settings on your PC or workstation.
Although we take great care when distributing the software, we ask that you also check for viruses.
Please check with the administrator of your environment regarding your security approach and operations (e.g., whether or not to install external applications).
In addition, the installation and operation of the development environment may require the intervention and configuration of the operating system (e.g., running an application whose developer is unknown; many of the development environments and tools introduced here do not have a built-in mechanism to prove the origin of the application) Please refer to the general information on how to configure.
To write an application using the MWX library, you will need the following:
MWSDK(Software Development Environment)
An editor for development (Microsoft's VisualStudio Code will be introduced)
Compiler toolchains, etc., are relatively less dependent on the environment, so they can be expected to work in many environments, but we recommend the Windows 10 version that is currently supported. If your system does not work due to differences in the operating environment, please prepare a separate environment by referring to the environment we have confirmed.
The following is the version we are using for development.
Windows11 21H2 (Visual Studio 2019)
FTDI driver must be running (to run MONOSTICK, TWELITE R)
Compiler toolchains, for example, are relatively less dependent on the environment, so they can be expected to work in many environments, but we recommend distributions that are currently supported. If your system does not work due to differences in the operating environment, please prepare a separate environment by referring to the environment that we have confirmed.
The following is the version we are using for development.
Ubuntu 18.04 LTS 64bit
Ubuntu 20.04 LTS 64bit
32bit systems are not supported.
Compiler toolchains, for example, are relatively less dependent on the environment, so they can be expected to work in many environments, but we recommend distributions that are currently supported. If your system does not work due to differences in the operating environment, please prepare a separate environment by referring to the environment that we have confirmed.
The following is the version we are using for development.
macOS 10.14 (Mojave, Intel)
macOS 12.4 (Monterey, Apple Silicon)
About Visual Studio Code and other development environments
For information on how to run and use the development environment, please refer to the information of its developer or community.
The use of Visual Studio Code (VSCode) is recommended for efficient code writing.
The MWX library requires more PC resources to interpret the code on VSCode, etc., since there are more header files to read compared to C language development.
The build results for Linux/macOS are different from the results for Windows 10. As far as we know, there is no difference in the normal operation, but the binary size tends to be a few percent larger, especially since the LTO of gcc is disabled.
If you have any doubts about the operation, be sure to run the build on Windows 10 and confirm that it reproduces before contacting us.
Creating a new project
To create a new project, copy the folder of an already existing sample act with a different name and edit the file name.
The destination folder does not have to be a folder under the MWSDK. However, the folder name must not contain any whitespace characters or Japanese names.
The file structure of the project is as follows (we'll use PingPong as an example)
Copy this PingPong folder to another location (but without Japanese characters or spaces in the folder name).
The only thing you need to edit is the file name PingPong.cpp. Change it to AlphaBravo.cpp, the same as the folder name.
Run build\build-BLUE.cmd and if a BIN file is generated, it' is done (Windows 10).
On Linux/macOS, run make TWELITE=BLUE to see if the build succeeds.
To add files to be built, edit build/Makefile. The .c .cpp files directly under the project will be added automatically, but other files will need to be edited.
See Makefile Description for how to edit the file.。
If you use VSCode, edit the definition under .vscode as necessary.
Most of the examples included in the TWELITE STAGE SDK are as follows
The source code for the TWELITE STAGE SDK library cites ${env:MWSDK_TWENET_LIBSRC}/include/** ${env:MWSDK_TWENET_LIBSRC}/src/**. This environment variable MWSDK_TWENET_LIBSRC is automatically set when the project is opened in VSCode from the TWELITE STAGE app.
For the build task, no additional options such as -D are set by default.
Install and Build
In order to write an application using the MWX library (called ACT in this document) and run it, you need to set up a development environment.
Building ACT
The application program written in the MWX library is called ACT. The first step is to build and write it.
About the build folder structure
About the build script
About building with Visual Studio Code (Described as VSCode)
This page describes several methods of building, all of which ultimately involve running the make command. Please refer to the Makefile description for details.
Depending on the OS environment, security warnings may appear when running each executable program (e.g. make, build toolchain like gcc). It is necessary to configure the settings to suppress the warning. (Please consult with yourself or your system administrator to determine if you wish to run the program with the warning suppressed.)
Open the folder MWSDK_ROOT (e.g. C:\MWSDK) where you have installed the MWSDK. It has the following structure
Tool act files such as compilers are stored under Act_samples. (Some of them are omitted below)
These acts are simple examples to help you write your own MWX library, but many of them have the following features
Obtaining sensor values
After obtaining the sensor value, send a wireless packet to the master
Sleeps for a period of time (or waits for an interrupt) after transmission is complete
The Parent-MONOSTICK act is used to receive and display packets. This act for the parent is output in ASCII format. (:00112233AABBCC.... .FF[CR][LF], and the middle part is a hexadecimal byte expressed by two ASCII characters. The trailing ? is also a two-character byte, but it becomes a checksum byte called LRC. Reference: ASCII format)
When trying to get it to work in practice, try the following combinations:
Now let's take a look inside the PingPong folder from within ACT.
You can also build other acts in Act_samples. In this case, the folder and file names should be read differently.
You must have a .cpp file with the same name as the folder directly under the folder.
If it is a small act, you can write it in this .cpp file. If you have a larger act, you can build it in multiple files by referring to the Makefile description.
The ACT file PingPong.cpp is located directly under the PingPong folder. If you change the name of the folder, make sure to rename the .cpp file to the same name as the folder.
Next, open the build folder.
It contains the scripts and Makefiles needed for the build.
Build by running make TWELITE={BLUE or RED} in the folder containing this Makefile. Building with VSCode is the same, calling make internally.
The TWELITE STAGE app can be used to build, write, and run. This section describes the TWELITE STAGE application from startup to build.
Connect MONOSTICK or TWELITE R to your USB port.
TWELITE is a sensitive electronic component and should be handled with care. Typical precautions are listed below.
Especially when TWELITE R is used, the electronic board is often in direct contact with the outside without a case, which may cause unintended shorts, noise, or other problems that prevent the USB device from operating properly.
In this case, closing the application and unplugging and plugging in the USB device will usually restore it. In the worst case, the USB device may be damaged or the PC may be corrupted.
Also, handle electronic circuit boards with care.
Circuit error.
Check the circuit again before turning on the power.
Be careful not to reverse-insert batteries or over-voltage.
Static electricity
Even a voltage that is not human-sensitive can cause a semiconductor failure. Even simple measures such as touching metal parts before working, wristbands, and special mats can have a reasonable effect.
Short-circuits caused by touching metal objects, etc.
Make sure that there are no metal objects near the electronic board. If clips or other objects are scattered around, this may cause a short circuit, or even a dangerous situation in which the battery heats up due to a large discharge.
Launch the executable TWELITE_Stage.{extension} located in the {TWELITE SDK installation} folder. (reference: TWELITE STAGE Application Manual - Usage)。
Below is an example of the screen while the TWELITE STAGE application is running. The main screen on the left and the command prompt screen are shown, but the main screen is usually used. The command prompt screen is not normally used, but it displays various information and input data from the TWELITE microcontroller serial port.
The main operations on the main screen are as follows
Left mouse click (selection)
Double right mouse click (return to previous screen)
Quickly press ESC twice, or ESC once on some screens (return to previous screen)
Hold down the Alt(Cmd) key (help screen)
Normal keyboard input (follow the screen)
(Reference: TWELITE STAGE App Manual - Key and Mouse Operations)
This is the first screen that appears when you start the TWELITE STAGE application. If TWELITE R or MONOSTICK is connected in advance, it will be listed on this screen. Select the TWELITE you wish to operate on this screen. It is also possible to select the TWELITE without selecting it on this screen.
(Reference: TWELITE STAGE App Manual)
After exiting the serial port selection screen, the main menu appears. Select the "Application Rewrite" menu for build and write.
(Reference: TWELITE STAGE App Manual)
Before selecting the application programming menu, please check the TWELITE connection and serial port selection. The serial port selection status can be checked on the help screen that appears by holding down the Alt(Cmd) key.
There are several categories of projects that can be referenced from the TWELITE STAGE application. HELP on the right side displays related information in a browser. Foldr displays the folder where the project is located.
If TWELITE is already connected, the TWELITE model is determined when the menu is selected. (Inside the TWELITE STAGE application, the build is performed according to the TWELITE model that has been determined.)
If an error occurs here, return to the main menu from this screen and reselect the menu. If necessary, deselect the serial port by pressing Alt(Cmd) + 0 on the TWELITE STAGE application and check the various connections, including the USB connection. Some USB connection errors may not be resolved until you reboot your computer.
(Reference: TWELITE STAGE App Manual)
Here, select "Act Build & Wrt" from the " Wrt Firmware" menu.
Project names, such as sample acts, are listed. The HELP on the right side displays the related information in a browser. The foldr displays the folder where the project is located.
Reference: TWELITE STAGE App Manual-Act Build & Wrt)
Here, select BRD_APPTWELITE in the project selection screen shown earlier.
Once selected, writing will be performed as shown in the following screen example. If an error is displayed, follow the on-screen instructions or return to the previous screen and try again.
(Reference: TWELITE STAGE App Manual-build screen)
When the programming is successfully completed, it will continue to Interactive settings mode (settings screen). However, the screen will not be displayed unless the firmware supports Interactive settings mode.
In Interactive settings mode, you can configure various settings, including TWELITE's wireless CHANNEL.
(Reference: TWELITE STAGE App Manual-Interactive settings mode)
Return to the root menu and select Viewer > Terminal.
This is a very simple terminal where you can check messages from TWELITE and input data into TWELITE.
The screen displays a message when a wireless transmission is made approximately every second. You can also transition to the Interactive settings mode screen by typing + + +.
(Reference: TWELITE STAGE App Manual-Terminal)
VSCode is a powerful editor for source editing, but it is also possible to build firmware for TWELITE microcontrollers on VSCode.
VSCode is started from the TWELITE STAGE application from the project listing in Build&Write menu. (Note: The settings is required at TWELITE STAGE App [Setting Menu] > Wrt Firmware > Open a folder with VSCode. For simplicity of configuration, the executable TWELITE_Stage_VSCode.{extension} is available for Windows, Linux, and macOS.)
Set "Open folder with code (VSCode)" to 1 in STAGE settings.
Press [VSCode] on the right end of the list of builds.
If VSCode is already launched, the necessary settings by setting the system environment variables may not be reflected. In this case, exit VSCode and start VSCode again from the TWELITE STAGE application.
Because of the use of system environment variables to reflect information, in principle, simultaneous operation of multiple TWELITE STAGES that reference different library folders may cause problems. If you open Terminal on VSCode and the environment variable MWSDK_ROOT is properly set, you can expect the build to be successful.
Firstly, open a workspace from TWELITE STAGE app that you want build. The attached workspace in TWELITE STAGE SDK has build task definitions for TWELITE microcontroller.
In the example below, a workspace is opened with an example screen of the English interface.
Open a workspace and select [Terminal>Run Task...].
Select the type of TWELITE radio module (BLUE/RED) and the act name to build. In the example below we have selected Build for TWELITE BLUE PingPong (for TWELITE BLUE/PingPong act). The build will start immediately after selection.
The progress of the build is shown in the TERMINAL section at the bottom of the screen.
If the build is successful, you will see a message about the creation of the .elf file, along with its size information (text data bss dec hex filename), as shown in the highlighted part of the screenshot above.
Also, a BIN file (in the above example, PingPong_BLUE_???.bin) file should be created under the build folder. Please check it.
The build definition adds a definition to convert folder names (e.g. /c/User/...) that do not conform to the Windows 10 file system (e.g. C:/User/...).
The conversion is not complete, but you can extract the filename and line number of the error from the compilation message.
The execution command in .vscode/tasks.json is sh -c "make ... | sed -E -e s#..." to rewrite the string of the drive name equivalent in the output message.
If the build does not work, check the error messages first; it is often easy to identify the cause of an error from a message on a line containing the string error.。
To be sure, clean (remove intermediate files in the objs_??? folder) and rerun the build to be sure. (All operations, including make clean, will fail if there are intermediate files left over from builds in other environments).
Additional information about building in the command line environment.
A working knowledge of the command line (e.g. bash) is required.
Depending on the OS environment, security warnings may appear when running each executable program. It is necessary to configure the settings to suppress the warning. (Please consult with yourself or your system administrator to determine if you wish to run the program with the warning suppressed.)
To build by command line, run make in a window where bash (or some other shell) is running. Make sure that the environment variable MWSDK_ROOT is set correctly beforehand. For example, if you install to /work/MWSTAGE/MWSDK, set ~/.profile as follows.
Run make from the command line (bash). If make is not available, you need to install a package. (The following is an example for Ubuntu Linux)
On Linux environments, install the make or build-essential package.
In the macOS environment, install Command Line Tools in Xcode.
On Windows, run {MWSTAGE SDK install}/MWSDK/WIN_BASH.cmd. Environment variables and make utility are already set.
A build should look like this:
See the Makefile description for more details.
When the build is done, the objs_??? folder is created and an intermediate file is created in it. This file is dependent on the environment in which it was compiled, so if any files from other environments are left, make will fail.
Deleting the objs_??? folder'' may resolve the make error.
Installing VSCode
VisualStudio Code (VSCode) is recommended to make Act (source code) writing easier. The attached Act contains a file that has been configured to ensure that the code is interpreted properly in VSCode.
VSCode reads source files and header files and interprets the source code, thus providing function definition information and function and method name completion to help you write source code. The MWX library requires more header files to be loaded than the C library. In comparison to C development, the MWX library requires more header files to be loaded and the editor may be slower in some environments.
The project settings of VSCode requires some information, such as library source code location, to analyse source codes. These inforamtion are passed by TWELITE STAGE app as environmental variable when launching VSCode. Therefore, application instance of VSCode should not be present when launching from TWELITE STAGE app, otherwise VSCode will not refer to these environmental values.
Please note that this support does not cover questions about how to install or use VSCode. Please refer to the information available in the public domain.
Depending on your environment, you may need to configure security settings or other settings in order to install the software. Please check with your system administrator whether installation is possible, and refer to the distributor or general information for instructions.
VSCode allows you to do the following:
Editing the source code
The IntelliSense based on source code interpretation (*not all definitions can be guaranteed to be interpreted correctly)
VSCode can be downloaded from the link below.
The code command must be enabled to invoke VSCode from TWELITE STAGE.
The following information is from code.visualstudio.com
macOS - PATH must be set so that the code command can be executed.
To enable Visual Studio Code to interpret C/C++ language descriptions, install a plugin.
C/C++ for Visual Studio Code
The MWX library examples include a .vscode definition. This definition uses the MWSDK_ROOT environment variable to identify the source code of the library (under {MWSDK_ROOT}/TWENET/current).
When launching VSCode from TWELITE STAGE, those settings such as MWSDK_ROOT will be setup automatically. In some cases, such as when you have already started VSCode, the settings may not be reflected.
VSCode's interpretation of source code is not always the same as the compiler's interpretation. Also, depending on how the source code is edited, the interpretation may be more incomplete.
Other platforms
Build definitions are provided so that some features (, , Serial object for console) can be built on other platforms. Only the necessary files are cut out.
The build definitions are stored in the {mwx library storage}/stdio folder. See (link is on GitHub) for build instructions.
Must be able to compile in C++11.
Ability to use C++11 standard library headers (utility, algorithm, functional, iterator, etc.)
new/delete/virtual are not used.
Memory allocation by new may be used in exceptional cases.
In serparser/pktparser, alloc_heap which uses new operator is processed by delete.
(Reference) However, the mwx library has been designed on the assumption that delete is not taken into account.
| Parents | Child | Remark |
|---|---|---|
| Example | Remark |
|---|---|
The parent device is started with the M1 pin low (GND level). In normal mode (always running), you can see it works like App_TweLite.
The system works with two children. When one of them sends a ping packet, the other sends a pong packet back.
Other
You can check the transmission of packets of the act for the child machine.
make TWELITE=BLUE
build for TWELITE BLUE
make TWELITE=RED
build for TWELITE RED
make cleanall
Delete intermediate files
Build definition Makefile
The Makefile is stored in build/Makefile and is pre-defined to build the act by running the make command.
MWSDK 2020-04 automatically detects the .cpp file in the project folder, so there is usually no need to modify the Makefile.
If the source file is to be stored in a subfolder, it will need to be edited.
MWSDK 2019-12 requires you to edit the Makefile if you have more than one .cpp file.
After copying the project folder from another environment, make sure to delete the build/objs_??? folder. If any intermediate files from the other environment remain, make will fail.
(MWSDK 2020-04) You can avoid errors by adding USE_APPDEPS=0 to clean and then running make again.
$ make USE_APPDEPS=0 TWELITE=BLUE clean
...
$ make TWELITE=BLUE
``
Specify the build target as BLUE or RED; for TWELITE BLUE, use make TWELITE=BLUE.
Run the build. Usually, you can omit this and use make TWELITE=BLUE.
Remove intermediate files from the build. Do this as make TWELITE=BLUE clean.
Remove all intermediate files. Do this as make cleanall, the same as removing all of the objs_??? folder in the build folder.
When set to 1 (the default), the build file is determined based on file dependencies. For example, if there is a change in a header file, the associated source file will be recompiled.
If set to 0, the makefile will not error if there are inconsistent intermediate files left.
Depending on the size of the act, and when defining behaviours, the source files are usually split and built separately.
One of the build files is {project folder name.cpp}.
If you want to define other files, edit the build/Makefile in your project folder.
The above is an example Makefile with sample PAL_AMB-bhv.
Specify the version number. This will be reflected in the build result file name.
During compilation, it is passed as a definition like -DVERSION_MAIN=0 -DVERSION_SUB=1 -DVERSION_VAR=0.
(MWSDK 2020-04) If you do not place files in subfolders, you no longer need to specify additions. All .c .cpp files in the project file will be added.
When you add a source file, you need APPSRC_CXX and APP_COMMON_SRC_DIR_ADD?.
If you place source files in a subfolder, you must specify the folder APP_COMMON_SRC_DIR_ADD?.
Append the name of the source file to `APPSRC_CXX'. This file name must not contain a folder name. Anything in a subfolder should also be specified without a folder (i.e. if the same filename is in a subfolder, the build will fail)
Next, specify the search path if the source files are stored in a location other than the project folder. You can set up to four.
The folder specification is relative to the Makefile.
A number of other options can be passed to the compiler linker.
| Designation | Remarks |
|---|---|
CXXFLAGS
Specify compilation options for C++ source files.
CFLAGS
Specify compile options for C/C++ source files.
INCFLAGS
Specify the include file for the header file.
OPTFLAGS
Define this if you have a special reason for wanting to apply a compile option other than -Os.
LDFLAGS
Specify linker options. (This is not mentioned in the comments of the Makefile above, but can be specified)
