The MWX library is intended to simplify the code notation of the TWELITE radio module. a program created with MWX is called an act. There are two types of acts: descriptions by loops and descriptions by events (called BEHAVIOR).

This page introduces the main features of ACT.

• Description by loop (setup(), loop()). Suitable for writing small-scale functions.

#include <TWELITE>
const uint8_t PIN_LED = 5;

void setup() {
  pinMode(PIN_LED, OUTPUT);
}

void loop() {
  if (TickTimer.available()) {
    uint32 t_now = millis();
    
    // blink LED every 1024ms
    digitalWrite(PIN_LED, (t_now >> 10) & 1 ? HIGH : LOW);
  }
}	

• Event-driven application description. It is possible to define various event and interrupt handlers, as well as a state machine within a class that is suitable for describing complex behavior of the application, and write code with good visibility. This description is called BEHAVIOR.

// myApp.hpp
...
class myApp : MWX_APPDEFS_CRTP(myApp) {
...
  void loop() {
    // main loop
  }
  
  void receive(mwx::packet_rx& rx) {
    // on receive
  }
};

// myApp.cpp
...
MWX_DIO_EVENT(12, uint32_t arg) {
		// on event from DIO12
}

• Simplify peripheral procedures. Defines class objects to handle commonly used UART, I2C, SPI, ADC, DIO, timer, and pulse counter.

void loop() {
  while(Serial.available() { 
    auto x = Serial.read(); ... } // serial message
  if (Analogue.available() {
    auto x = Analogue.read(...); } // adc values
  if (Buttons.available() { 
    Buttons.read(...); } // DIO changes
  if (the_twelite.receiver.available()) { 
    auto&& rx = the_twelite.receiver.read(); } // on rx packet
}

• A simple relay network is defined. This relay network is implemented in the same way as the TWELITE standard application, and is characterized by the fact that individual addresses are managed by 8-bit logical IDs, and that wireless packets can be sent to the network immediately after power-on because there is no communication to build the network.

#include <TWELITE>
#include <NWK_SIMPLE>

void setup() {
  ...
  auto&& nwksmpl = the_twelite.network.use<NWK_SIMPLE>();
	nwksmpl << NWK_SIMPLE::logical_id(0xFE) 
	           // set Logical ID. (0xFE means a child device with no ID)
	        << NWK_SIMPLE::repeat_max(3);
	           // can repeat a packet up to three times.
}

void loop() {
  ...
  vTransmit();
  ...
}

void vTransmit() {
  if (auto&& pkt =
    the_twelite.network.use<NWK_SIMPLE>().prepare_tx_packet(); 
  pkt << tx_addr(0x00)  // to parent 
	  	<< tx_retry(0x3); // set retry
	
	pack_bytes(pkt.get_payload() // prepare payload data
	    , uint8_t(0x01)
	    , uint16_t(analogRead(PIN_ANALOGUE::A1))
	    , uint16_t(analogRead_mv(PIN_ANALOGUE::VCC)));
	
	pkt.transmit(); // transmit!
}

• Board definition for PAL and MONOSTICK. Easy handling of sensors etc. on the board.

#include <TWELITE>
#include <PAL_AMB> // include the board support of PAL_AMB

void setup() {
	auto&& brd = the_twelite.board.use<PAL_AMB>(); // use PAL AMB
	uint8_t u8dip = brd.get_DIP_SW();   // check DIP s/w status
	brd.set_led(LED_TIMER::BLINK, 100); // LED switchs on/off every 100ms
	...
	
	// start capture of sensors
	brd.sns_SHTC3.begin();
}

void loop() {
	if (TickTime.available()) { // check every ms
		auto&& brd = the_twelite.board.use<PAL_AMB>();

		if (brd.sns_LTR308ALS.available()) {
		  Serial << brd.sns_SHTC3..get_temp();
		} else {
		  // notify sensor that 1ms passed.
			brd.sns_SHTC3.process_ev(E_EVENT_TICK_TIMER);
		}
	}
}

Download the TWELITE STAGE SDK distribution archive (e.g. ZIP) and extract it to an appropriate folder.

Set Environmental variables

If you want to build with other than TWELITE STAGE application, please set the environment variables (e.g. MWSDK_ROOT).

MWSDK_ROOT, MWSDK_ROOT_WINNAME(for Windows10) need to be set.

Windows10,11

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:

MWSDK_ROOT=C:/MWSTAGE/MWSDK/
MW_ROOT_WINNAME=C:\MWSTAGE\MWSDK\

Linux

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.

$ cd $HOME
$ echo MWSDK_ROOT=/foo/bar/MWSTAGE/MWSDK>>.profile
$ echo export MWSDK_ROOT>>.profile

macOS

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.

$ cd $HOME
$ echo MWSDK_ROOT=/foo/bar/MWSTAGE/MWSDK>>.profile
$ echo export MWSDK_ROOT>>.profile

Warranty and License

This document is also handled under MW-SLA as a part of this library package part.

This software is not officially supported by Mono Wireless Ltd. Please note that we may not be able to respond to your inquiries. Please understand beforehand.

In response to reports of defects, Mono-Wireless, Inc. does not promise to fix or improve the problem.

There are also cases where the software may not work depending on the customer's environment, such as the package installed.

/* Copyright (C) 2019-2022 Mono Wireless Inc. All Rights Reserved.
   Released under MW-SLA-*J,*E (MONO WIRELESS SOFTWARE LICENSE
   AGREEMENT) */

To create a new project, copy the folder of an already existing sample act with a different name and edit the file name.

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.

Edit Build Definition

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.

Configuration for VSCode

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.

The MWX library is designed to make the programming of TWELITE modules easier and more extensible. Based on the TWENET C library that has been used in the MWSDK, the MWX library has been developed as a library for the application development layer.

   Act (USER APPs)... 
+-----------------------+
| MWX C++ LIB           |
+---------------+       |
| TWENET C LIB  |       |
+------------+----------+
| MAC LAYER  | AHI APIs |
+-----------------------+
| TWELITE HARDWARE      |
+-----------------------+

The name of the MWX library is Mono Wireless C++ Library for TWELITE, where MW comes from MonoWireless, and C++ -> CXX -> double X -> WX, where MW and WX are combined to form MWX.

The code written using this library is called "ACT".

Notation, etc.

This section describes the notation used in this explanation.

auto&&

This is called a universal reference, and is often used in standard libraries. In our library, auto&& is used in most cases

#include <algorithm>
int v[] = { 1, 3, -1, 5, 10 };
auto&& result = std::minmax_element(std::begin(v), std::end(v));
Serial << "min=" << int(result.first)
       << ",max=" << int(result.second);

about namespace

The namespace, inline namespace, and using are used to redefine names and so on. Some of them are abbreviated in the explanation.

Restrictions (TWENET)

The MWX library has not been developed to support all the functions of the underlying libraries and functions (functions in the TWNET C library, microcontroller peripheral functions provided by semiconductor vendors, and IEEE802.15.4 functions).

Restrictions (Using C++)

The MWX library is written in the C++ language, and the act description is also written in C++. However, not all functions are available even in the C++ language. Please pay particular attention to the following points.

• You can allocate memory with the new and new[] operators, but you cannot destroy the allocated memory, and most C++ libraries that allocate memory dynamically are virtually unusable.

• The constructor of the global object is not called. Note： If necessary, initialization can be done including a call to the constructor by initializing it as in the initialization function ((void*)&obj_global) class_foo();).

• exception cannot be used.

• Unable to use virtual functions.

• Due to the above limitations, only some of the C++ standard libraries such as STL can be used.

※ This is a description of what we know.

about the library source code

The source code can be found at the followings:

• {MWSDK install dir}/TWENET/current/src/mwx

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.

Updating

After the release of the TWELITE STAGE distribution package, fixes and additions are stored in the GitHub repository. Please replace the location of the distribution package if necessary.

Updating MWX library code

1. Click on the link for each release to clone the Git file or download the source code in zip format.

2. Replace the contents of the following folders.

Update before major release

Updated information prior to major releases may be posted on the above link.

0.2.0 - 2022-03-01

• changed Wire object that reserves memory in heap area.

• changed function name from G_OCTET() to G_BYTE()](api-reference/funcs/utility/byte-array-utils.md to avoid name conflict in utils.h.

• changed an order of vAHI_DioInterruptEnable() in the attachIntDio() for code efficiency.

• added secondary network behavior the_twelite.network2 to support universal receiver (receive packets from NWK_LAYERED, NWK_SIMPLE or networkless packets in the same executable code.)

• introduced MWX_Set_Usder_App_Ver() function to set application version during MWX intitialization, mainly for interactive mode.

• • added new[] operators for EASTL

• pre-compled most of source codes in MWX to quicker compile.

• fixed: DIO events were being passed on to unrelated ports.

0.1.9 - 2021-12-15

主な改定内容

• Added an internal procedure to allow output using Serial class objects in Interactive settings mode. (Serial._force_Serial_out_during_intaractive_mode())

0.1.8 - 2021-09-09

Main revisions

• Serial1port and alternate port were not properly defined.

• Enabled to change the baud rate of (Serial UART0).

• • If you don't define a callback function, you can use the previous procedure.

• Wrong definition ID for interactive mode setting<STG_STD> and some default values.

• Added support for changing the default values of channel and logical device IDs in addition to AppID in interactive mode settings<STG_STD>.

• added support for setting the_twelite and <NWK_SIMPLE> objects in interactive mode <STG_STD> object for some settings.

• added support for setting the default value of the number of retransmissions in <NWK_SIMPLE>.

• Serial(UART0) input and output from the application is not performed while the interactive mode screen<STG_STD> is displayed.

• added CUE::PIN_SET, PAL???"":PIN_SET (Since it is unnatural to use PIN_BTN for CUEs without buttons)

• Move namespace of random() to mwx::.

• MONOSTICK watchdog setting is now done in 32ms units.

• When sleep was performed using BRD_TWELITE, the pins were not initialized correctly upon recovery.

0.1.7 - 2020-12-03

Major Revisions.

• Added method to receive other packets (without network usage) that are not in NWK_SIMPLE format when using NWK_SIMPLE. Add NWK_SIMPLE::receive_nwkless_pkt() to initialize NWK_SIMPLE. When using this packet information, use only the TWENET C library layer structure by .get_psRxDataApp() and the data array obtained by .get_payload(). Information obtained from other methods of the incoming packet (auto&& rx = the_twelite.receiver.read()) is undefined.

• Refine get_stream_helper() code and read/write position API.

• Fixed bugs in smplbuf::get_stream_helper().

0.1.6 - 2020-10-09

Major revisions

• Modified so that div100(), which calculates the quotient and remainder, can be output to Serial, etc.

• Changed implementation of smplbuf<> array class. The inheritance from mwx::stream is removed to reduce memory consumption, and a helper class and an inheritance class are defined separately.

• Added mwx_printf() mwx_snprintf()` function.

• added the_twelite.stop_watchdog() and the_twelite.restart_watchdog() functions.

• mwx::stream maintenance: operator bool() is obsolete. Disable timeout when .set_timeout(0xff) is set to 0xff in the read timeout setting. Add definition of << operator.

• Add scale functions between 8bit and 0..1000 with no division.

• Added division by 10,100,1000 (quotient and remainder at the same time) div10(), div100(), div1000(). Restricted the value range and composed mainly of multiplication and bit shift.

• Added corresponding methods for encrypted packets.

  • packet_rx::is_secure_pkt() : determine if received packet is encrypted or not.

  • STG_STD::u8encmode() : Obtain encryption setting in interactive mode.

  • STG_STD::pu8enckeystr() : Obtain encryption key byte sequence in interactive mode.

• Serial1: Default port is DIO11(TxD), DIO9(RxD) because they are usually assigned to I2C, though DIO14,15 overlap with I2C in the semiconductor specification.

• The calculation of the baud rate is omitted for the main baud rates.

• Serial: The proxy functions for Serial: available() and read() are now held only by void*, and the specification memory is reduced by 8 bytes.

• Add typedef boolean.

• Network: added support for encryption.

  • The first parameter is the encryption key, and the second parameter is true, so that plaintext packets are also received. packets are also received.
• Added sensor support for SHT3x and BME280

• Sensor: added a mechanism to exchange configuration parameters and status in legacy code (C library wrapper class).

• Sensors: I2C address can be specified for SHT3x and BME280.

• Configuration: added hide_items(). Unnecessary items can be deleted.

• Added `H/W UTIL menu' to display DI status, I2C probe, and PAL EEPROM contents.

• Configuration: Add encryption related menus.

• I2C related fixes (to improve compatibility with code implemented using TwoWire class)

  • Processing of requestFrom(false) did not work correctly because there was no code to send the NO_STOP message when processing requestFrom(false).

  • Added TwoWire class name alias.

  • Modified not to initialize multiply in begin() process.

  • Added setClock() method (but it is a dummy function and does nothing).

  • Added WIRE_CONF::WIRE_? KHZ added. Added the main configuration values for the bus clock.

0.1.5 - 2020-08-05

Download in bulk

Major revisions

0.1.4 - 2020-07-29 (MWSDK2020_07_UNOFFICIAL)

Download in bulk

Major revisions.

• Addition of delayMilliseconds() function

• Addition of digitalReadBitmap() function

• Improved accuracy of delay().

• Fixed the problem that Serial1 instance was not defined

• Fixed problem with Analogue interrupt handler not being called

0.1.3 - 2020-05-29

Support for MWSDK202020_05

• Duplicate checker duplicate_checker was not removed as expected due to incomplete initialization, etc.

• The implementation of format() was made less machine-dependent. If 64-bit arguments are included, the number of arguments is limited.

0.1.2 - 2020-04-24

Support for MWSDK2020_04

• Fixed initialization problem with Timer0..4

• Changed internal processing of mwx::format()

• Added experimental code to support interactive mode

0.1.1 - 2020-02-28

Fixed problems with handling of relay flags in packets

0.1.0 - 2019-12-23

First release (included in SDL Dec 2019)

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)

Windows10,11

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)

Linux

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.

macOS

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.

Differences by build environment

This section describes the specifications, limitations, notes in this document, and design memos for the C++ language used in the MWX library.

Design Policy

• The application loop description is intended to be similar to the commonly used API system, but the implementation should be tailored to the characteristics of TWELITE.

• TWENET is an event-driven code description, and it should be classed so that it can be handled. The above classifications will encapsulate the behavior of the application.

• Event-driven and loop descriptions should be able to coexist.

• Simplify procedures by classifying typical peripherals. Make them accessible by loop descriptions whenever possible.

• Simplify the procedures for using the boards we sell, such as MONOSTICK/PAL, by creating classes. (For example, to automate the use of an external watchdog timer.

• Application classes and board classes should be made available through a unified procedure, introducing the idea of polymorphism. (For example, to load application classes with several behaviors at startup, and to avoid defining the connection code of the TWENET C library each time).

• There are no restrictions on the use of C++ functionality. For example, it provides a means to simplify typical procedures such as packet construction and decomposition, which are complicated in handling wireless packets.

• The operator -> should be avoided as much as possible, and the API should be based on reference types in principle.

About the C++ Compiler

Version

gcc version 4.7.4

C++ standard

C++11 (For compiler support status, please refer to the general information.)

C++ limitations

※ This is a description of what we know.

• You can allocate memory with the new and new[] operators, but you cannot destroy the allocated memory; most C++ libraries that allocate memory dynamically are virtually unusable. It is used for objects that are created only once and not destroyed after that.

• The constructor of the global object is not called. Note: If necessary, you can initialize the constructor call by using the initialization function (setup()) as shown in (new ((void*)&obj_global) class_foo();).

• Exception cannot be used.

• Unable to use virtual function.

Design Memo

This section contains information that will help you understand the code when referring to the MWX library code.

Current implementation

Due to the limited time available for implementation, some of the details may not be sufficiently developed. For example, const is not fully taken into account in many classes.

namespace

We have the following policy for namespaces.

• In principle, definitions are placed in a common namespace mwx.

• We want to be able to use namespaces without identifiers, but we want to require identifiers for some definitions.

• Class names should be relatively long, and those used by users should be defined as aliases.

Classes, Functions, and constants are defined within the namespace of mwx names (more precisely, mwx::L1 enclosed in inline namespace L1), with a few exceptions. inline namespace is specified so that definitions that require the specification of mwx:: can coexist with those that do not. The reason why inline namespace is specified is to allow definitions that require the specification of mwx:: to coexist with those that do not.

Most of the definitions do not require namespace names to be specified by using namespace. These specifications are made in using_mwx_def.hpp in the library.

// at some header file.
namespace mwx {
  inline namespace L1 {
    class foobar {
      // class definition...
    };
  }
}

// at using_mwx_def.hpp
using namespace mwx::L1; // Definitions in mwx::L1 can be accessed without mwx::.
                         // But mwx::L2 needs mwx::.

Exceptionally, relatively short names can be specified as mwx::crlf, mwx::flush. These are placed in the inline namespace mwx::L2; using namespace mwx::L2; will allow them to be used without specifying the namespace name.

Also, some class names have a using specification.

The std::make_pair used in the MWX library is specified using.

CRTP(Curiously recursive template patterns.)

The following example shows how to implement an interface called interface() in a Derived class that inherits from Base, and calls the Derived::print() method from Base.

template <class T>
class Base {
public:
  void intrface() {
    T* derived = static_cast<T*>(this);
    derived->prt();
  }
};

class Derived : public class Base<Derived> {
  void prt() {
     // print message here!
     my_print("foo");
  }
}

The following are the main classes used in the MWX library.

• Basic parts of event processingmwx::appdefs_crtp

• state machine public mwx::processev_crtp

• stream mwx::stream

Virtualization with CRTP

In the CRTP class, the class from which it inherits is different for each instance. For this reason, it is not possible to cast it to a parent class and treat it as a member of the same family, nor is it possible to use advanced polymorphism such as virtual functions or RTTI (runtime type information).

The following is an example of implementing the above CRTP example with a virtual function: CRTP cannot manage instances together in the same array as in Base* b[2].

class Base {
	virtual void prt() = 0;
public:
	void intrface() { prt(); }
};

class Derived1 : public Base {
	void prt() { my_print("foo"); }
};

class Derived2 : public Base {
	void prt() { my_print("bar"); }
};

Derived1 d1;
Derived2 d2;
Base* b[2] = { &d1, &d2 };

void tst() {
	for (auto&& x : b) { x->intrface(); }
}

The MWX library solves this problem by defining a dedicated class for storing class instances of CRTP and defining a similar interface to this class. An example code is given below.

class VBase {
public:
	void* p_inst;
	void (*pf_intrface)(void* p);

public:
	void intrface() {
		if (p_inst != nullptr) {
			pf_intrface(p_inst);
		}
	}
};

template <class T>
class Base {
	friend class VBase;
	static void s_intrface(void* p) {
		T* derived = static_cast<T*>(p);
		derived->intrface();
	}
public:
	void intrface() {
		T* derived = static_cast<T*>(this);
		derived->prt();
	}
};

class Derived1 : public Base<Derived1> {
	friend class Base<Derived1>;
	void prt() { my_print("foo"); }
};

class Derived2 : public Base<Derived2> {
	friend class Base<Derived2>;
	void prt() { my_print("bar"); }
};

Derived1 d1;
Derived2 d2;

VBase b[2];

void tst() {
	b[0] = d1;
	b[1] = d2;

	for (auto&& x : b) {
		x.intrface();
	}
}

The VBase class member variable p_inst stores a pointer to an object of type Base , and pf_intrface is a member function pointer to Base::s_intrface. Base::s_intrface invokes the T::intrface method by being passed an object instance of itself as an argument and static_casting it to the T type.

Storage in VBase is implemented here by overloading the = operator (see below for source examples).

In the above example, when making a call to b[0].intrface(), Base::s_intrface() will be called with reference to the VBase::pf_intrface function pointer. In addition, a call to Derived1::intrface() will be made. This part is expected to be expanded inline by the compiler.

It is also possible to perform a conversion from the VBase type to the original Derived1 or Derived2 through a forced cast, but there is no way to directly know the type of the pointer stored in void*. Although there is no completely safe way to do this, a unique ID (TYPE_ID) is provided for each class as shown below, and the ID is checked when the cast is executed (get() method). If the get() method is called with a different type, an error message will be displayed.

BIf a pointer is stored as a Base type, it may not be correctly converted to a T type (e.g., when T has multiple inheritance), so a static_assert is used to determine at compile time that the pointer is derived from a Base type by using is_base_of in <type_trails>.

#include <type_trails>

class Derived1 : public Base<Derived1> {
public:
   static const uint8_t TYPE_ID = 1;
}

class Derived1 : public Base<Derived1> {
public:
   static const uint8_t TYPE_ID = 2;
}

class VBase {
  uint8_t type_id;
public:
	
	template <class T>
	void operator = (T& t) {
		static_assert(std::is_base_of<Base<T>, T>::value == true,
						"is not base of Base<T>.");

		type_id = T::TYPE_ID;
		p_inst = &t;
		pf_intrface = T::s_intrface;
	}
	
  template <class T>
  T& get() {
    static_assert(std::is_base_of<Base<T>, T>::value == true,
					  "is not base of Base<T>.");
			
		if(T::TYPE_ID == type_id) {
			return *reinterpret_cast<T*>(p_inst);
		} else {
			// panic code here!
		}
  }
}

Derived1 d1;
Derived2 d2;

VBase b[2];

void tst() {
	b[0] = d1;
	b[1] = d2;
	
  Derived1 e1 = b[0].get<Derived1>(); // OK
  Derived2 e2 = b[1].get<Derived2>(); // OK
  
  Derived2 e3 = b[1].get<Derived1>(); // PANIC!
}

new, new[] operator

The microcontroller in the TWELITE module does not have enough memory nor does it have advanced memory management. However, the area from the end of the microcontroller's memory map to the stack area is available as a heap area, which can be allocated as needed. An overview of the memory map is shown in the figure below, where APP is the RAM area allocated by the application code, HEAP is the heap area, and STACK is the stack area.

|====APP====:==HEAP==..   :==STACK==|
0                                  32KB

Even if it is not possible to delete, the new operator may be useful in some situations. For this reason, the new and new[] operators are defined as follows: pvHear_Alloc() is a function for allocating memory provided by the semiconductor library, and the same is true for u32HeapStart and u32HeapEnd. 0xdeadbeef is a dummy address. Please do not point out that it is strange that beef is dead.

void* operator new(size_t size) noexcept {
    if (u32HeapStart + size > u32HeapEnd) {
        return (void*)0xdeadbeef;
    } else {
        void *blk = pvHeap_Alloc(NULL, size, 0);   
        return blk;
    }
}
void* operator new[](size_t size) noexcept {
    return operator new(size); }
void operator delete(void* ptr) noexcept {}
void operator delete[](void* ptr) noexcept {}

Since exceptions cannot be used, there is no way to deal with failures. Also, if you continue to allocate without being aware of the memory capacity, there is a possibility of interference with the stack area.

Container class

The MWX library does not use the container classes provided by the standard library, considering the small resources of the microcontroller and the lack of dynamic memory allocation, but defines two simple container classes. The container classes have defined iterators and begin() and end() methods, so you can use some of the range for statements and STL algorithms.

smplbuf<int16_t, alloc_local<int16_t, 16>> buf;
buf.push_back(-1); // push_back() は末尾に追加
buf.push_back(2);
...
buf.push_back(10);

//範囲for文
for(auto&& x : buf) { Serial << int(x) << ',' }
//アルゴリズム std::minmax
auto&& minmax = std::minmax_element(buf.begin(), buf.end());
Serial << "Min=" << int(*minmax.first)
       << ",Max=" << int(*minmax.second);

About memory in container classes

In the container class, the memory allocation method is specified as a parameter of the template argument.

variable parameter

In the MWX library, variable number arguments are used for operations on byte sequences, bit sequences, and printf equivalent operations. The example below shows the process of setting 1 to the specified bit position.

// packing bits with given arguments, which specifies bit position.
//   pack_bits(5, 0, 1) -> (b100011) bit0,1,5 are set.

// The first function of recursive extraction
template <typename Head>
constexpr uint32_t pack_bits(Head head) { return  1UL << head; }

// Extract head and transfer the rest of the parameters to pack_bits 
//by recursive call
template <typename Head, typename... Tail>
constexpr uint32_t pack_bits(Head head, Tail&&... tail) {
  return (1UL << head) | pack_bits(std::forward<Tail>(tail)...);
}

// コンパAfter ILL, the following two will have the same result.
constexpr uint32_t b1 = pack_bits(1, 4, 0, 8);
// b1 and b2 are the same! 
const uint32_t b2 = (1UL << 1)|(1UL << 4)|(1UL << 0)|(1UL << 8);

In this process, the parameter pack of template (typename... part of template) to perform recursive processing to expand the arguments. In the above example, since constexpr is specified, the calculation is done at compile time and the result is equivalent to macro definition or const value specification such as b2. It can also behave as a function that dynamically calculates variables as arguments.

In the following example, the expand_bytes function is used to store a value in a local variable from the received packet data string. In the case of using a parameter pack, since the type of each argument can be known, it is possible to store values of different sizes and types from the byte string of the received packet, as shown below.

auto&& rx = the_twelite.receiver.read(); // received packet

// Variable that stores the contents of the packet after expansion
// The payload of a packet is a sequence of bytes, arranged as follows.
//   [B0][B1][B2][B3][B4][B5][B6][B7][B8][B9][Ba][Bb]
//   <message       ><adc*  ><vcc*  ><timestamp*    >
//   * Numerical types are big-endian.
uint8_t msg[MSG_LEN];
uint16_t adcval, volt;
uint32_t timestamp;

// expand packet payload
expand_bytes(rx.get_payload().begin(), rx.get_payload().end()
		, msg       // 4bytes of msg
		, adcval    // 2bytes, A1 value [0..1023]
	  , volt      // 2bytes, Module VCC[mV]
	  , timestamp // 4bytes of timestamp
);

Iterator

An iterator is an abstraction of a pointer, which has the effect of making it possible to access data structures as if they were pointers, even if the data structures are not memory-contiguous, for example.

smplque<uint8_t, alloc_local<uint8_t, 5> > que;
que.push('a'); que.push('b'); que.pop(); que.push('c'); ...

auto&& p = que.begin();
auto&& e = que.end();

while(p != e) { // p advanced to e = all elements processed
  Serial << *p;
  ++p; // イThe prefix operator is used for incrementing the terrator.
  　　　// In this case, writing p++ will result in a copy of the iterator 
       // in the code, although it is likely to be optimized by the compiler.
}

#include <algorithm>
#include <cctype>

// Character conversion using lambda expressions
std::for_each(que.begin(), que.end(), 
  [](uint8_t& x) { x = std::toupper(x); });

// range-for statement
for (uint8_t x : que) {
  Serial << x;
}

The following example shows the use of an iterator for a FIFO queue that cannot be accessed continuously with a normal pointer, and also an iterator that extracts only a specific member of the FIFO queue structure (the X axis in the example).

//A queue with 5 elements, whose elements are the 4-axis structures of XYZT
smplque<axis_xyzt, alloc_local<axis_xyzt, 5> > que;

// Input data for testing.
que.push(axis_xyzt(1, 2, 3, 4));
que.push(axis_xyzt(5, 2, 3, 4));
...

// Access using iterators as structures
for (auto&& e : v) { Serial << int(e.x) << ','; }

// Extract the X axis in the queue.
auto&& vx = get_axis_x(que);
// Access with X-axis iterator
for (auto&& e : vx) { Serial << int(e) << ','; }

// Since it is an iterator of int16_t elements, 
//the STL algorithm (max-min) can be used.
auto&& minmax = std::minmax_element(vx.begin(), vx.end());

The following is an excerpt of the implementation of an iterator for the smplque class. In this iterator, the queue object is managed by its entity and its index. The part of the queue that is discontiguous in memory (ring buffer structure where the next to the tail must point to the beginning) is solved by smplque::operator []. If the addresses of the objects match and the indices match, the iterators point to the same thing.

This implementation part also includes the typedefs required by , allowing more STL algorithms to be applied.

class iter_smplque {
	typedef smplque<T, alloc, INTCTL> BODY;

private:
	uint16_t _pos; // index
	BODY* _body;   // point to original object

public: // for <iterator>
	typedef iter_smplque self_type;
	typedef T value_type;
	typedef T& reference;
	typedef T* pointer;
	typedef std::forward_iterator_tag iterator_category;
	typedef int difference_type;

public: // pick some methods
	inline reference operator *() {
		return (*_body)[_pos];
	}
	
	inline self_type& operator ++() {
		_pos++;
		return *this;
	}
};

構造体を格納したコンテナ中の、特定構造体メンバーだけアクセスするイテレータは少々煩雑です。構造体のメンバーにアクセスするメンバー関数を予め定義しておきます。このメンバー関数をパラメータ（R& (T::*get)()）としたテンプレートを定義します。Iterはコンテナクラスのイテレータ型です。

Iterators that access only specific structure members in the container that contains the structure are a bit complicated. Define a member function to access the structure members in advance. Next, define a template with this member function as a parameter (R& (T::*get)()). "Iter" is the iterator type of the container class.

struct axis_xyzt {
    int16_t x, y, z;
    uint16_t t;
    int16_t& get_x() { return x; }
    int16_t& get_y() { return y; }
    int16_t& get_z() { return z; }
};

template <class Iter, typename T, typename R, R& (T::*get)()>
class _iter_axis_xyzt {
    Iter _p;
    
public:
    inline self_type& operator ++() {
        _p++;
        return *this; }

    inline reference operator *() {
        return (*_p.*get)(); }
};

template <class Ixyz, class Cnt>
class _axis_xyzt_iter_gen {
    Cnt& _c;
    
public:
    _axis_xyzt_iter_gen(Cnt& c) : _c(c) {}
    Ixyz begin() { return Ixyz(_c.begin()); }
    Ixyz end() { return Ixyz(_c.end()); }
};

// It's long, so shorten it with using
template <typename T, int16_t& (axis_xyzt::*get)()>
using _axis_xyzt_axis_ret = _axis_xyzt_iter_gen<
    _iter_axis_xyzt<typename T::iterator, axis_xyzt, int16_t, get>, T>;

// Generator to extract X axis
template <typename T>
_axis_xyzt_axis_ret<T, &axis_xyzt::get_x>
get_axis_x(T& c) {
    return _axis_xyzt_axis_ret<T, &axis_xyzt::get_x>(c);
}

The operator * that accesses the value calls the member function described above. The *_p is the axis_xyzt structure, and (*_p.*get)() calls _p->get_x() if &axis_xyzt::get_x is specified in T::*get.

The _axis_xyzt_iter_gen class implements only begin(), end() and generates the above iterators. Now you can use range for statements and algorithms.

This class name is very long and difficult to write in the source code. We will prepare a generator function to generate this class. In the example below, it is get_axis_x() in the last line. By using this generator function, the description becomes as simple as auto&& vx = get_axis_x(que); as shown in the beginning.

This iterator for extracting only the axes can also be used with the smplbuf class of array type as well.

Implementing interrupt, event, and state handlers

In order to describe the application behavior by user-defined classes, typical handlers need to be defined as mandatory methods, but it is complicated to define all the other numerous interrupt handlers, event handlers, and state machine state handlers. Ideally, only those defined by the user should be defined, and only that code should be executed.

class my_app_def {
public: // Define required methods
	void network_event(twe::packet_ev_nwk& pEvNwk) {}
	void receive(twe::packet_rx& rx) {}
	void transmit_complete(twe::packet_ev_tx& pEvTx) {}
	void loop() {}
	void on_sleep(uint32_t& val) {}
	void warmboot(uint32_t& val) {}
	void wakeup(uint32_t& val) {}
	
public: // It is cumbersome to make these descriptions mandatory.
  // DIO interrupt handler: There are 20 types.
  // DIO event handler: There are 20 types.
  // Timer interrupt handler: There are five types
  // Timer event handlers: there are 5 types
  // ...
}

In the MWX library, a large number of DIO interrupt handlers (on TWELITE hardware, a single interrupt, but for ease of use, a handler is assigned to each DIO) are defined as empty handlers using templates, and user-defined member functions are defined by specializing the templates.

// hpp file
class my_app_def : class app_defs<my_app_def>, ... {
  // Empty handler
  template<int N> void int_dio_handler(uint32_t arg, uint8_t& handled) { ; }

  ...   
  // Implement only number 12.
  
public:
  // Callback function called from TWENET
  uint8 cbTweNet_u8HwInt(uint32 u32DeviceId, uint32 u32ItemBitmap);
};

// cpp file
template <>
void my_app_def::int_dio_handler<12>(uint32_t arg, uint8_t& handled) {
  digitalWrite(5, LOW);
  handled = true;
  return;
}

void cbTweNet_u8HwInt(uint32 u32DeviceId, uint32 u32ItemBitmap) {
  uint8_t b_handled = FALSE;
  switch(u32DeviceId) {
  	case E_AHI_DEVICE_SYSCTRL:
      if (u32ItemBitmap & (1UL << 0)){int_dio_handler<0>(0, b_handled);}
      if (u32ItemBitmap & (1UL << 1)){int_dio_handler<1>(1, b_handled);}
      ...
      if (u32ItemBitmap & (1UL << 12)){int_dio_handler<12>(12, b_handled);}
      ...
      if (u32ItemBitmap & (1UL << 19)){int_dio_handler<19>(19, b_handled);}
    break;
  }
}

The actual user-described code has been simplified by macroizing and including header files, but the above includes the code necessary for the explanation.

The my_app_def::cbTweNet_u8HwInt() is called from the interrupt handler from TWENET. in the cpp file, only int_dio_handler<12> is instantiated with the specialization described in it. file is instantiated from a template in the hpp file. The rest are instantiated from templates in the hpp file.

  	case E_AHI_DEVICE_SYSCTRL:
      if (u32ItemBitmap & (1UL << 0)){;}
      if (u32ItemBitmap & (1UL << 1)){;}
      ...
      if (u32ItemBitmap & (1UL << 12)){
          int_dio_handler<12>(12, b_handled);}
      ...
      if (u32ItemBitmap & (1UL << 19)){;}
      break;
      
    // ↓　↓　↓
    
    // 結局、このように最適化されることが期待できる。
   	case E_AHI_DEVICE_SYSCTRL:
      if (u32ItemBitmap & (1UL << 12)){
        // int_dio_handler<12> もinline展開
        digitalWrite(5, LOW);
        handled = true;
      }
      break;
    

Eventually, we can expect that the compiler optimization will determine that codes other than number 12 are meaningless and disappear from the code (however, we do not guarantee that they will be optimized as described above).

In other words, in user code, if you want to define the behavior at interrupt 12, just write int_dio_handler<12> (Note: to enable DIO interrupt, you need to call attachInterrupt()). Handlers that are not registered are expected to be low-cost calls due to compile-time optimization.

// mwx_appcore.cpp
void wakeup() __attribute__((weak));
void wakeup() { }

Stream class

The stream class is mainly used for input/output of UART (serial port), and MWX library mainly defines procedures for output. But some of them are also defined for input.

This section describes the implementation required by the derived class.

template <class D>
class stream {
protected:
	void* pvOutputContext; // TWE_tsFILE*
public:
  inline D* get_Derived() { return static_cast<D*>(this); }
	inline D& operator << (char c) {
		get_Derived()->write(c);
		return *get_Derived();
	}
};

class serial_jen : public mwx::stream<serial_jen> {
public:
 	inline size_t write(int n) {
		return (int)SERIAL_bTxChar(_serdef._u8Port, n);
	}
};

The above is an implementation of the write() method that writes a single character. The stream<serial_jen> of the parent class accesses the serial_jen::write() method using the get_Drived() method to perform casting.

Define methods such as write(), read(), flush(), and available() as needed.

template <class D>
class stream {
protected:
	void* pvOutputContext; // TWE_tsFILE*
public:
	inline tfcOutput get_pfcOutout() { return get_Derived()->vOutput; }
	
	inline D& operator << (int i) {
		(size_t)fctprintf(get_pfcOutout(), pvOutputContext, "%d", i);
		return *get_Derived();
	}
};

class serial_jen : public mwx::stream<serial_jen> {
	using SUPER = mwx::stream<serial_jen>;
	TWE_tsFILE* _psSer; // Low-level structure for serial output
public:
  void begin() {
    SUPER::pvOutputContext = (void*)_psSer;
  }
  
	static void vOutput(char out, void* vp) {
		TWE_tsFILE* fp = (TWE_tsFILE*)vp;
		fp->fp_putc(out, fp);
	}
};

By get_pfcOutput(), the vOutput() function defined in the derived class is specified, and pvOutputContext is passed as its parameter. In the above example, when the << operator is called with int type, serial_jen::vOutput() and TWE_tsFILE* which is already set for UART are passed to the fctprintf() function.

Worker object for Wire, SPI

In the Wire class, it is necessary to manage the communication from start to end when sending and receiving with a 2-wire device. This section describes the contents of the description of using the worker object.

if (auto&& wrt = Wire.get_writer(SHTC3_ADDRESS)) {
	Serial << "{I2C SHTC3 connected.";
	wrt << SHTC3_TRIG_H;
	wrt << SHTC3_TRIG_L;
	Serial << " end}";
}

This is an excerpt of the periph_twowire::writer class, which inherits from mwx::stream<writer> to implement the stream interface, and implements the write() and vOutput() methods to use the steam interface. To use the steam interface, the write() and `vOutput() methods are implemented.

The constructor calls the method to start communication for 2-wire serial and the destructor calls the method to end communication. Also, the operator bool() operator returns true if the communication of the 2-wire serial device is successfully started.

class periph_twowire {
public:
	class writer : public mwx::stream<writer> {
		friend class mwx::stream<writer>;
		periph_twowire& _wire;
	
	public:
		writer(periph_twowire& ref, uint8_t devid) : _wire(ref) {
	  	_wire.beginTransmission(devid); // Start communication with constructor
		}
	
		~writer() {
			_wire.endTransmission(); // Communication terminated by destructor
		}
	
		operator bool() {
			return (_wire._mode == periph_twowire::MODE_TX);
		}
	
	private: // stream interface
		inline size_t write(int n) {
			return _wire.write(val);
		}
	
		// for upper class use
		static void vOutput(char out, void* vp) {
			periph_twowire* p_wire = (periph_twowire*)vp;
			if (p_wire != nullptr) {
				p_wire->write(uint8_t(out));
			}
		}
	};
	
public:
	writer get_writer(uint8_t address) {
		return writer(*this, address);
	}
};
class periphe_twowire Wire; // global instance

// ユーザコード
if (auto&& wrt = Wire.get_writer(SHTC3_ADDRESS)) {
	Serial << "{I2C SHTC3 connected.";
	wrt << SHTC3_TRIG_H;
	wrt << SHTC3_TRIG_L;
	Serial << " end}";
}

The get_writer() method creates an object wrt. Due to the Return Value Optimization (RVO) of the C++ compiler, the writer is created directly in the wrt, so no copy is made and the bus running in the constructor is not initialized multiple times. However, RVO is not guaranteed by the C++ specification, and just in case, the MWX library defines copy, delete assignment operators, and move constructors (although it is unlikely that move constructors will be evaluated).

The wrt in the if clause is first initialized by the constructor and starts communication at the same time. If there is no error at the start of communication, the bool operator at the time of conditional judgment returns true, and the processing in the scope of the if clause takes place. If there is no error at the start of communication, the bool operator at the conditional judgment returns true, and the processing in the if clause scope is performed. When the scope is exited, the destructor terminates the 2-wire serial bus. If there is no communication partner, false will be returned and the wrt object will be destroyed.

It overrides the definition of operator << (int), which is specific to Wire and SPI. The default behavior of the stream is to convert numeric values to strings and output them, but Wire and SPI rarely write numeric strings to the bus, and on the contrary, we often want to input literals of numeric type such as configuration values. We will change this behavior.

			writer& operator << (int v) {
				_wire.write(uint8_t(v & 0xFF));
				return *this;
			}

In this example, the int type values are truncated to 8 bits and the values are output.

The following is a supplement to the terminology used in this document.

General terms

SDK (TWELITE SDK, MWSDK)

Software Development Environment

IEEE802.15.4

This is the radio standard used by the TWELITE radio module; as long as you use the MWX library, you do not need to be aware of the details of the radio standard.

packet

The smallest unit of communication in wireless communications.

The maximum amount varies depending on the communication method and settings during communication, but in the MWX library standard communication <NWK_SIMPLE>, the amount of data a user can send in one packet is 90 bytes.

payload (of a packet)

It refers to the body of data contained in a wireless packet.

node

It refers to a radio station in a wireless network.

MWX library specific terms

ACT

A program created using this library. This refers to its source code or the program that runs.

A program in the form of an event, among other ACTs. The source code or the program that runs it.

BEHAVIORs are described by a single class definition, which describes callback functions from TWENET, events, and interrupt processing, all in one place. There are three types of behaviors available in the MWX library:

• Application BEHAVIOR: A class defined by the user that describes the application in an event-driven manner.

• Board BEHAVIOR: A class to simplify the use of the functionality of the board that implements the TWELITE radio module.

• Network BEHAVIOR: A class for simplifying procedures in wireless networks.

Behavior names are enclosed in < >. For example, the behavior name for a simple relay network is <NWK_SIMPLE>.

Class objects

In the description of this library, objects that are declared globally from the beginning in the library are referred to as class objects: Serial, Wire, etc. These class objects can be used without any procedure or by performing the start procedure.

Class objects that consume relatively large amounts of memory allocate memory along with the initialization parameters during the initialization procedure (.setup() or .begin() method).

C++ terms

C++

The C++ language.

C++11

One of the versions of the C++ standard, meaning C++ as of 2011, which was standardized by ISO in 2011. It has been greatly enhanced since its predecessor, C++03. Newer versions such as C++14 and C++17 are available.

Class

A collection of procedures that focus on some data in a single place. A structure contains the procedures for handling that structure. It actually develops into a much deeper topic, but please refer to technical books.

In C++, the keywords struct and class are essentially the same thing, and a class is a class regardless of which keyword it is declared with.

struct myhello {
  int _i;
  void say_hello() { printf("hello %d\n", _i); }
};

If the above class definition was also done in C, for example, it would look like the following:

typedef struct _c_myhello {
  int _i;
  void (*pf_say_hello)(struct _c_myhello *);
} c_myhello;

void say_hello(c_myhello*p) { p->pf_say_hello(); }
void init_c_my_hello(c_myhello*p) {
  p->pf_say_hello = say_hello;
}

Wrapper class

It is a class that includes existing C libraries and their internal structures, and adds C++ specific functionality to make it easier to use. In some cases, the description "wrapped ~structure" is used in the explanation.

Method, Member function

A function that is defined in a class and is associated with the class.

struct myhello {
  int _i;
  void say_hello() { printf("hello %d\n", _i); } //Method
};

Object (instance)

A class is materialized (allocated memory).

void func() {
    myhello obj_hello; // obj_hello is an object of myhello class
    obj_hello._i = 10;
    obj_hello.say_hello();
}

In this explanation, object and instance are treated as having the same meaning.

Constructor

Initialization procedure at the time of object creation.

struct myhello {
  int _i;
  void say_hello() { printf("hello %d\n", _i); }
  
  myhello(int i = 0) : _i(i) {} // constructor
};

void my_main() {
  myhello helo(10); // Here, the constructor is called and set to _i=10
}

Destructor

This is the procedure when the object is destroyed, paired with the constructor.struct myhello {

  int _i;
  void say_hello() { printf("hello! %d\n", _i); }
  
  myhello(int i = 0) : _i(i) {} // constructor
  ~myhello() {
    printf("good bye! %d\n", _i);
  } // destructor
};

abstract class

In C++, polymorphism is achieved by virtual classes. Specifically, a class that defines a pure virtual function specified by the virtual keyword.

struct Base {
  virtual void say_hello() = 0;
};

struct DeriveEng : public Base {
  void say_hello() { printf("Hello!"); }
};

struct DeriveJpn : public Base {
  void say_hello() { printf("Kontiwa!"); }
};

Scope

In the C/C++ language, think of it as a scope enclosed in { }. The objects created in this scope are destroyed when they leave the scope. The destructor is called at this time.

The following is an explicitly scoped version of helo2, which is discarded after line 8 and the destructor is called.

void my_main() {
  myhello helo1(1);
  helo1.say_hello();
  
  {
    myhello helo2(2);
    helo2.say_hello();
  }
}

// hello! 1
// hello! 2
// good bye! 2
// good bye! 1

MThe MWX library uses the following notation. Here, the validity period of an object declared within the conditional expression of an if statement (older C languages such as C89 do not allow declarations in such a place) is within {} of the if statement.

struct myhello {
  int _i;
  void say_hello() { printf("hello! %d\n", _i); }
  operator bool() { return true; } // Operators for judgment in if()
  
  myhello(int i = 0) : _i(i) {} // constructor
  ~myhello() { printf("good bye! %d\n", _i); } // constructor
};

// Function to create a myhello object (generator)
myhello gen_greeting() { return my_hello(); }

void my_main() {
  if (myhello x = gen_greeting()) {
    // The object x in myhello is valid during the if statement
    x.say_hello();
  }
  // object x is destroyed when exiting the if minute
}

For example, a two-wire serial bus is a procedure where there is a start and end procedure and the bus is manipulated by an object only during that time. After the object is created, if the bus is properly connected, the true clause of the if statement is executed and the bus is written or read by the created object. When the bus read/write operation is completed, the if statement is exited and the destructor is called to terminate the bus usage.

const uint8_t DEV_ADDR = 0x70;
if (auto&& wrt = Wire.get_writer(DEV_ADDR)) { //バスの初期化、接続判定
	wrt(SHTC3_TRIG_H); // 書き出し
	wrt(SHTC3_TRIG_L);
} // バスの利用終了手続き

Namespace

The namespace are actively used in C++ to avoid duplication of definition names. To access a definition in a namespace, use::.

namespace MY_NAME { // 名Namespace declaration
  const uint8_t MYVAL1 = 0x00;
}

...
void my_main() {
  uint8_t i = MY_NAME::MYVAL1; // reference of MY_NAME
}

Template

Think of a template as an extension of a C macro.

template <typename T, int N>
class myary {
  T _buf[N];
public:
  myary() : _buf{} {}
  T operator [] (int i) { return _buf[i % N]; }
};

myary<int, 10> a1; // Array of type int with 10 elements
myary<char, 128> a2; // Array of char type with 128 elements

This example defines a simple array, where T and N are template parameters, where T is the type name and N is a number, and defines an array class of type T with N elements.

nullptr

In C++11, NULL pointers are now written as nullptr.

reference type

In C++, reference types are available. This is similar to access by pointer, but with the restriction that it must refer to an object.

For functions with pass-by-reference parameters like the one below, the value of i can be rewritten in incr().

void incr(int& lhs, int rhs) { lhs += rhs; }

void my_main() {
  int i = 10; j = 20;
  incr(i, j);
}

In the example of the template explanation, the return type of operator[] is changed to T&. By doing so, it becomes possible to perform assignment operations directly on the data inside the array, such as a[0]=1.

template <typename T, int N>
class myary {
  T _buf[N];
public:
  myary() : _buf{} {}
  T& operator [] (int i) { return _buf[i % N]; }
};

myary<int, 10> a1;
void my_main() {
  a1[0] = 1;
  a1[1] = 2;
}

type inference

C++11 introduces the auto keyword for type inference. This allows the compiler to infer the type of an object from its initialization description, thus omitting the need to specify the specific type name. This is effective in cases where class names using template are very long.

In most of the explanations, auto&&, which is called universal reference, is used. Universal references can be written here without being aware of passing references.

auto&& p = std::make_pair("HELLO", 5);
       // const char* と int のペア std::pair

container

A class for storing multiple objects of a specific data type such as arrays is called a container. An array class such as myary mentioned in the template example is also called a container.

Iterator, .begin(), .end()

A pointer in C can be thought of as a way to access a contiguous set of memory elements in a continuous manner from the beginning to the end. The simplest implementation of a FIFO queue is a ring buffer, but there is no memory continuity. Even such a data structure can be described in the same way as a pointer using an iterator.

The methods .begin() and .end() are used to get the iterator. The iterator that points to the beginning of the container is obtained with .begin(). The iterator that points to the next to the end is obtained with .end(). The reason for using the next to the end instead of the end is for the clarity of the loop description in the for and while statements, and to handle the case where the number of elements stored in the container is zero.

my_queue que; // my_queue is a class of queue

auto&& p = que.begin();
auto&& e = que.end();

while(p != e) {
  some_process(*p);
  ++p;
}

In the above, some_process() is applied to each element of the que using the iterator p. p is incremented by the ++ operator as an iterator that points to the next element. Even if the container has a data structure that cannot be described by a pointer, it can be processed in the same way as using a pointer.

Since .end() indicates the next to the end, the end decision of the while statement is as simple as (p ! = e), which is concise. If there is no element in the queue, .begin() returns the same iterator as .end(). If there are no elements in the queue, .begin() will return the same iterator as .end(), which is the next iterator after the iterator for the unstored elements.

For a contiguous container in memory, its iterator will usually be a normal pointer. It is not expected to be a large overhead during its operation.

C++ standard library

The C++ standard library includes the STL (Standard Template Library), which is part of the MWX library.

Algorithm

In C, for example, the process of finding the maximum or minimum value is written separately depending on the type. In C++, you can use templates, iterators, etc. to describe such operations independently of their types. This is called an algorithm.

// Return the iterator with the maximum value with any iterator as a parameter.
template <class Iter>
Iter find_max(Iter b, Iter e) {
  Iter m = b; ++b;
  while(b != e) {
    if (*b > *m) { m = b; }
    ++b;
  }
  return m;
}

For example, the algorithm to find the maximum value as shown above. This algorithm is type-independent. (It is called generic programming.)

#include <algorithm>

auto&& minmax = std::minmax_element( // Algorithm for obtaining the maximum minimum
  que.begin(), que.end());

auto&& min_val = *minmax.first;
auto&& max_val = *minmax.second;

Here we specify an iterator for que and apply the algorithm std::minmax_elenet to obtain its maximum and minimum. std::minmax_elemet is defined in the C++ standard library. Its return value is std::pair, which combines any two values. The algorithm calculates the maximum and minimum values if the elements indicated by the iterator can be compared with each other using operators such as <,>,==. The return type is also derived from the iterator type.

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.

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.

Installing VSCode

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.

Special note for each OS

The code command must be enabled to invoke VSCode from TWELITE STAGE.

The following information is from code.visualstudio.com

Installing plug-ins

To enable Visual Studio Code to interpret C/C++ language descriptions, install a plugin.

• C/C++ for Visual Studio Code

Notes

The Makefile is stored in build/Makefile and is pre-defined to build the act by running the make command.

Parameters for make.

TWELITE=

Specify the build target as BLUE or RED; for TWELITE BLUE, use make TWELITE=BLUE.

all

Run the build. Usually, you can omit this and use make TWELITE=BLUE.

clean

Remove intermediate files from the build. Do this as make TWELITE=BLUE clean.

cleanall

Remove all intermediate files. Do this as make cleanall, the same as removing all of the objs_??? folder in the build folder.

USE_APPDEPS=0 or 1

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.

Makefile definition

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.

VERSION_???

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.

Adding source files

When you add a source file, you need APPSRC_CXX and 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.

Compile and linker options

A number of other options can be passed to the compiler linker.

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)

About the build folder structure

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 must have a .cpp file with the same name as the folder directly under 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.

Building with TWELITE STAGE App. (Normal)

The TWELITE STAGE app can be used to build, write, and run. This section describes the TWELITE STAGE application from startup to build.

0. TWELITE Connection

Connect MONOSTICK or TWELITE R to your USB port.

1. Launch the TWELITE STAGE application

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)

2. Serial port selection

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.

3. Main Menu

After exiting the serial port selection screen, the main menu appears. Select the "Application Rewrite" menu for build and write.

4. Wrt Firmware (Application programming) menu

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.)

4. Project Selection

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.

5. Build & Wrt(Programming)

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.

6. Go to Interactive settings mode

In Interactive settings mode, you can configure various settings, including TWELITE's wireless CHANNEL.

7. Terminal screen

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 + + +.

About building with VSCode (Optional)

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.

Build with VSCode

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.

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.

Build on command line (Linux/macOS)

Additional information about building in the command line environment.

Linux, macOS

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)

Windows

On Windows, run {MWSTAGE SDK install}/MWSDK/WIN_BASH.cmd. Environment variables and make utility are already set.

Building

A build should look like this:

Example commands

About intermediate files

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.

To help you understand how the ACT works, we have prepared some samples.

Introduction to sample ACTs

Several samples are provided to help you understand how the act works.

Short ACT with no wireless communication and only microcontroller functions

Example of ACT description with I2C sensor

This is an example of a wireless sensor implementation that connects an I2C sensor and sends wireless packets while performing a brief operation by sleeping. Since this is a relatively simple and typical structure, it is recommended that you refer to it after reviewing act0 through act4.

Basic ACT for wireless communication

These are samples of sending or receiving wireless packets, each implemented from a slightly different perspective.

ACT on Parent Node side

Refer to this when implementing your own Receiving Parent Node application.

ACT to add Interactive settings mode

The explanation of the ACT using Interactive settings mode describes the general flow of the program. There are no major differences between the explanations for any of the samples. (Here we quote BRD_I2C_TEMPHUMID)

ACT to operate sensors and other devices

This sample obtains sensor information from built-in peripherals and external sensor devices.

ACT to use TWELITE PAL

Although a standard PAL application is written into TWELITE PAL, it is possible to write a description using ACT without using the PAL application. The MWX library provides standard procedures for MOTION SENSE PAL use.

This is a sample for various PAL boards. This sample acquires sensor values, transmits these valuse, and sleeps on the PAL board.

The following is an example of an advanced application, which is a little more complicated to describe than the above ACT.

ACT, which introduced the stand-alone function

Get the latest version.

Common description

The following items are common settings in the Act sample and are explained below.

const uint32_t APP_ID = 0x1234abcd;
const uint8_t CHANNEL = 13;
const char APP_FOURCHAR[] = "BAT1";

• 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.

This act uses MONOSTICK as a parent device. It outputs the data payload of packets from the child machine to the serial port. It can display packets in many samples of sample acts.

Act Features

• Receives packets from the child of the sample act and outputs them to the serial port.

How to use Act

TWELITE and wiring required

Please check the following default settings at first.

• Application ID: 0x1234abcd

• Channel: 13

Act Explanation

Declaration part

includes

// use twelite mwx c++ template library
#include <TWELITE>
#include <MONOSTICK>
#include <NWK_SIMPLE>
#include <STG_STD>

• <NWK_SIMPLE> Loads the definition of a simple relay net

• <STG_STD> Loads the interactive mode definition

Other

// application ID
const uint32_t DEFAULT_APP_ID = 0x1234abcd;
// channel
const uint8_t DEFAULT_CHANNEL = 13;
// option bits
uint32_t OPT_BITS = 0;

/*** function prototype */
bool analyze_payload(packet_rx& rx);

Declaration of default values, function prototypes, etc.

setup()

auto&& brd = the_twelite.board.use<MONOSTICK>();
auto&& set = the_twelite.settings.use<STG_STD>();
auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();

In setup(), first load the <MONOSTICK> board behavior, the <STG_STD> interactive mode behavior, and the <NWK_SIMPLE> behavior using use<>. This procedure is always done in setup().

set << SETTINGS::appname("PARENT"); // Title in the settings screen
set << SETTINGS::appid_default(DEFAULT_APP_ID); // Application ID Default
set << SETTINGS::ch_default(DEFAULT_CHANNEL); // channel default
set << SETTINGS::lid_default(0x00); //LID Default
set.hide_items(E_STGSTD_SETID::OPT_DWORD2, E_STGSTD_SETID::OPT_DWORD3, E_STGSTD_SETID::OPT_DWORD4, E_STGSTD_SETID::ENC_KEY_STRING, E_STGSTD_SETID::ENC_MODE);
set.reload(); // Read settings from non-volatile memory
OPT_BITS = set.u32opt1(); // Example of reading (option bits)

• appname→ Act name that appears in the title line of the configuration screen

• appid_default→ Default Application ID

• ch_default→ Default channel

• lid_default→ Default value of device ID (LID)

• .hide_items()→ Item Hide Settings

Always call .reload() before reading the configuration values. Each set value has its own method for reading, such as .u32opt1().

the_twelite
	<< set                    // Reflects interactive mode settings
	<< TWENET::rx_when_idle() // Set RF to receive when idle.
	;

// Register Network
nwk << set;		            // Reflects interactive mode settings
nwk << NWK_SIMPLE::logical_id(0x00) // Only the LID is reconfigured.
	;

brd.set_led_red(LED_TIMER::ON_RX, 200); // RED (on receiving)
brd.set_led_yellow(LED_TIMER::BLINK, 500); // YELLOW (blinking)

Procedures for controlling LED lighting are available in the <MONOSTICK> board behaviour.

The first line sets the red LED to switch on for 200 ms after receiving a radio packet. The first parameter LED_TIMER::ON_RX means when a radio packet is received; the second specifies the lighting time in ms.

The second line specifies the blinking of the LEDs: the first parameter LED_TIMER::BLINK specifies the blinking, the second parameter is the blinking on/off switching time: every 500ms the LEDs are switched on and off (i.e. Repeat blinking with a 1 s cycle).

the_twelite.begin(); // start twelite!

Procedure for starting the_twelite, which did not appear in act0..4, but must be called if you have configured the_twelite or registered various behaviours.

loop()

There is no processing during loop() in this sample.

void loop() {
}

on_rx_packet()

Callback function called when a packet is received. In this example, some output is produced for the received packet data.

void on_rx_packet(packet_rx& rx, bool_t &handled) {  
	Serial << ".. coming packet (" << int(millis()&0xffff) << ')' << mwx::crlf;

  ...
  
	// packet analyze
	analyze_payload(rx);
}

analyze_payload()

The analyze_payload() called at the end of the function contains code to interpret some sample act packets. Refer to the code in correspondence with the packet generation part in the sample act.

bool b_handled = false;

uint8_t fourchars[4]{};
auto&& np = expand_bytes(
	    rx.get_payload().begin(), rx.get_payload().end()
		, fourchars
    );
    
if (np == nullptr) return;

// display fourchars at first
Serial
	<< fourchars 
	<< format("(ID=%d/LQ=%d)", rx.get_addr_src_lid(), rx.get_lqi())
	<< "-> ";
	

This function first reads the four-character identification data into the fourchars[4] array.

char fourchars[5]{}; // Allocate 5 bytes including the terminating character `\0`.
auto&& np = expand_bytes(
	    rx.get_payload().begin(), rx.get_payload().end()
		, make_pair((char *)fourchars, 4)
	);

Processing is then carried out for the 4-byte header. Here, the packets of the sample act Slp_Wk_and_Tx are interpreted and the contents are displayed.

// Slp_Wk_and_Tx
if (!b_handled && !strncmp(fourchars, "TXSP", 4)) {
	b_handled = true;
	uint32_t tick_ms;
	uint16_t u16work_ct;

	np = expand_bytes(np, rx.get_payload().end()
		, tick_ms
		, u16work_ct
	);

	if (np != nullptr) {
		Serial << format("Tick=%d WkCt=%d", tick_ms, u16work_ct);
	} else {
		Serial << ".. error ..";
	}
}

Set b_handled to true so that the other interpreters' decisions are skipped.

"TXSP" packets contain the values of a system timer count of type uint32_t and a dummy counter of type uint16_t. Each variable is declared and read using the expand_bytes() function. The difference from the above is that the first parameter is np as the first pointer to read. The tick_ms and u16work_ct are given as parameters and the value stored in the payload is read as a big-endian format byte sequence.

If the readout is successful, the contents are output and the process is complete.

Define and output your own ASCII format

It is structured by ASCII format in a user-defined order.

smplbuf_u8<128> buf;
mwx::pack_bytes(buf
	, uint8_t(rx.get_addr_src_lid()		// Logical ID of the sender
	, uint8_t(0xCC)											   // 0xCC
	, uint8_t(rx.get_psRxDataApp()->u8Seq)	// Sequence number of the packet
	, uint32_t(rx.get_addr_src_long())	// Serial number of the sender.
	, uint32_t(rx.get_addr_dst())		// destination address
	, uint8_t(rx.get_lqi())			// LQI:Link Quality Indicator
	, uint16_t(rx.get_length())		// Number of following bytes
	, rx.get_payload() 			// data payload
);

serparser_attach pout;
pout.begin(PARSER::ASCII, buf.begin(), buf.size(), buf.size());

Serial << "FMT PACKET -> ";
pout >> Serial;
Serial << mwx::flush;

The first line declares a buffer as a local object to store the data sequence before conversion to ASCII format.

The second line uses pack_bytes() to store the data sequence into the buf mentioned earlier. See comments in the source code for the data structure. The pack_bytes() parameter can also be a container of the form smplbuf_u8 (smplbuf<uint8_t, ALLOC>).

Lines 13, 14 and 17 are the declaration, configuration and output of the serial parser.

Dump output including NWK_SIMPLE header.

The first output (which is prevented from being executed by if(0)) displays all data including the control data of <NWK_SIMPLE>. There are 11 bytes of control data. Normally, the control information is not directly referenced.

serparser_attach pout;
pout.begin(PARSER::ASCII, rx.get_psRxDataApp()->auData, 
    rx.get_psRxDataApp()->u8Len, rx.get_psRxDataApp()->u8Len);

Serial << "RAW PACKET -> ";
pout >> Serial;
Serial << mwx::flush;

// Reference: packet structure of the control unit.
// uint8_t  : 0x01 fixws
// uint8_t  : LID of sender
// uint32_t : Long address (Serial Number) of sender
// uint32_t : Destination address
// uint8_t  : Number of repeating

The second line sets the buffer for the serial parser. It specifies an already existing data array, i.e. the payload part of the incoming packet. serparser_attach pout declares the serial parser using an already existing buffer. The first parameter of pout.begin() specifies the corresponding format of the parser as PARSER::ASCII, i.e. ASCII format; the second specifies the first address of the buffer; the third specifies the The length of valid data in the buffer and the fourth specifies the maximum length of the buffer. The fourth parameter has the same value as the third, as it is for output and is not used for format interpretation.

Output to the serial port in line 6 using the >> operator.

The Serial << mwx::flush in line 7 is a specification to wait until the output of data that has not been output here is finished. (Serial.flush() is the same process.)

Template code.

setup()

Set the_twelite to set the application ID APP_ID, the radio channel CHANNEL and the receive presence.

It also generates nwk and specifies the child machine address 0xFE. This address means that this is an unnamed child machine that has not been addressed by a child machine.

This is the procedure to start the_twelite, it didn't appear in act0..4, but you should call it if you set up the_twelite or register various behaviors.

begin()

Called only once after setup() on startup. Only displays a message.

loop()

Input detection of buttons (switches).

Input from serial.

If Serial.available() is true, the input from the serial port is stored. It reads one character from the serial and processes it according to the input character.

Enter t for wireless transmission

When 't' is input, sending is done. In this sample, the tx_busy flag is used to prevent continuous input.

Type s to sleep.

The system will sleep for 5000ms=5 seconds. After recovery, wakeup() is executed.

wakeup()

First to be called on sleep wake up. Display of message only.

Transmit()

This is the minimum procedure for making a transmission request.

When you leave this function, the request has not yet been executed. You need to wait a while. In this example we have set a delay of 100-200ms for the start of the transmission, so the transmission will not start until 100ms at the earliest.

on_tx_comp()

Called on completion of a transmission; ev contains the transmission ID and completion status.

on_rx_packet()

When a packet is received, the sender's address information is displayed.

Slp_Wk_and_Tx is a template source code for an application which, after a regular wake-up, does something (e.g. acquires sensor data) and sends the result as a wireless packet.

ACT features.

• After starting up, the system goes through an initialization process and then goes to sleep.

  1. setup()Initialise

  2. begin() Run sleep

• After waking up from sleep, the state variables are initialized and the actions are performed in the following order

  1. wakeup() wakes up from sleep, performs each initialization

  2. loop()/INIT->WORK_JOB state: does some processing (in this Act, the counter is updated every TickCount for 1ms and moves to TX state after a count determined by a random number)

  3. loop()/TX state: Make a request to send

  4. loop()/WAIT_TX state: Waiting for transmission completion

  5. loop()/EXIT_NORMAL state: Run sleep (back to 1.)

• loop()/EXIT_FATAL state :Resetting the module if an error occurs

Description of the ACT

Declarations

Includes

To send packets, <NWK_SIMPLE> is included. Also, basic definitions such as application ID are in "Common.h".

State definition.

In order to describe the sequential processing in loop(), this sample uses the concept of a state machine (state transition). It uses <SM_SIMPLE>, which summarizes the processing of very simple state transitions.

An enum STATE is defined in Common.h for the following states.

The step declared here contains functions for managing state, timeouts and waiting for processing.

Sensor data.

In this sample we do not process the sensor data, but we prepare dummy data for explanation.

setup()

Initializes variables and class objects.

• Initialization of the step state machine

• Initialization of the_twelite class object

• Register and initialize the network <NWK_SIMPLE> (register DEVICE_ID).

This is followed by the initiation of class objects and hardware.

This is the procedure to start the_twelite, it didn't appear in act0..4, but you should call it if you set up the_twelite or register various behaviors.

begin()

Called only once, immediately after setup(). The SleepNow() function is called to perform the first sleep procedure.

wakeup()

Called immediately after waking up. Here, it initializes the sensor data area and outputs a message on waking.

loop()

The above code is a simplified version of the actual code.

step.b_more_loop() is set to true if there is a state transition by .next(). The purpose of this is to execute the code of the next state (case clause) without escaping loop() when a state transition occurs.

Below is a description of each state.

STATE::INIT

Initialises the sensor values of the dummies. One is determined randomly by an add counter and one by a counter stop value.

STATE::WORK_JOB

In the WORK_JOB state, we work on a timer every 1ms; every Tick timer becomes TickTimer.available(); every Tick timer adds a counter and when it reaches dummy_work_ct_max, we move to the next state STATE::TX .

STATE::TX

Call the Transmit() function to request packet transmission. If the request succeeds, the function transits to STATE::WAIT_TXEVENT and waits for the completion of transmission. Here, we use the timeout and flag functions of the SM_SIMPLE state machine to wait for completion (it is simple to determine the value of a variable by changing its value in the waiting loop).

We don't usually expect a single request to fail, but if it does, it will go to the STATE::EXIT_FATAL exception handling state.

STATE::WAIT_TX

Waiting for completion of transmission is judged by setting the flag of the state machine function with on_tx_comp() described later. The timeout is judged by the elapsed time since .set_timeout() was done by calling .is_timeout().

Normally you will get a completion notice whether the transmission succeeds or fails, but it will time out and go to STATE::EXIT_FATAL for exception handling.

STATE::EXIT_NORMAL

Call SleepNow() to start the sleep process.

STATE::EXIT_FATAL

As a critical error, a system reset is performed.

SleepNow()

Periodic sleep is performed. The sleep time is set to a constant time blur using the random() function. This is because when the transmission cycles of several devices are synchronized, the failure rate may increase significantly.

Before sleeping, the state of the SM_SIMPLE state machine is set by calling .on_sleep().

Transmit()

This function requests to send a wireless packet to the parent device with ID=0x00. The data to be stored is a four-character identifier (FOURCC) commonly used in the Act sample, plus the system time [ms] and a dummy sensor value (sensor.dummy_work_ct_now).

The first step is to get an object that contains the transmitted packets. This object can then be manipulated to set the data and conditions for transmission.

In the mwx library, the if statement is used to get an object and the bool decision of the object is true. Here, a board object is retrieved by the_twelite.network.use<NWK_SIMPLE>(), and a packet object is retrieved by .prepare_tx_packet() of the board object. Failure to retrieve the packet object is not normally expected, but when it does occur, it is when the transmit queue is full and the transmit request cannot be accepted. Since this example is for a single transmission only, the error is limited to an unexpected serious problem.

This function can be specified by a variable number of arguments. The first parameter is an array object obtained from .get_payload().

• make_pair(FOURCC,4) : make_pair is from the C++ standard library and creates a std::pair object. It means to write out 4 bytes from the beginning for string type.(This is done to explicitly specify the number of bytes to be written, as the topic of including or excluding the end of an array of string types is confusing)

• If uint32_t type data is specified, 4 bytes of data are written in big-endian order.

• The same applies to data of type uint16_t.

Finally, .transmit() is called to request sending. The return value is of the type MWX_APIRET. After the request, the actual transmission takes place, which may take several to several tens of milliseconds to complete, depending on the transmission parameters and the size of the transmission. On completion, on_tx_comp() is called.

on_tx_comp()

This is a system event that is called when the transmission is complete. Here, it is set to complete by .set_flag().

Send a PING wireless packet from one of the two serially connected TWELITEs and receive a PONG wireless packet back from the other.

how to use act

Required TWELITE

Two of any of the following.

Explanation of ACT

Include

Declaration section

• Sample act common declarations

• Prototype declarations for longer processes (sending and receiving), since they are made into functions

• Variables for holding data in the application

セットアップ setup()

The general flow of the program is the initial setup of each section and the start of each section.

the_twelite

This object is the core class object for manipulating TWENET.

the_twelite に設定を反映するには << を用います。

Use << to reflect the setting in the_twelite.

• TWENET::appid(APP_ID) to specify the Application ID.

• TWENET::channel(CHANNEL) to specify the channel.

• TWENET::rx_when_idle() Specifies that the receive circuit is open.