Warranty and License

The Mono Wireless Software License Agreement (MW-SLA) applies to anything in this package that is not specifically described in the 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) */

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);
		}
	}
}

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.

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

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

description sample. For details, please refer to for details.

Class objects are predefined objects in the MWX library, such as the_twelite, which handles TWENET, and objects for using peripherals.

Each object must be initialized by calling the .setup() or .begin() method. (Only Serial objects that use UART0 do not require initialization.)

Instance of a helper class to output a newline code (CR LF) for the << operator of mwx::stream.

Serial << "hello world!" << mwx::crlf;

Called at the re-initialization of code execution, with no peripheral API or initialization.

Helper class for mwx::stream << operator to output numeric types as big-endian byte strings.

Serial << mwx::bigendian(0x1234abcdUL);

// output binary -> 0x12 0x34 0xab 0xcd

constructor

template <typename T>
bigendian::bigendian(T v)

Obtain the system time, [ms].

uint32_t millis()

The system tick time is updated by TickTimer interrupt.

Unregisters the interrupt handler.

void detachIntDio(uint8_t u8pin)

It is called only once before the first call to the loop() function; since TWENET is already initialized, there is no need to consider constraints such as setup().

The main usage is to

• Displaying startup messages

• Writing code for testing

• Sleep transition immediately after startup

• Processing that is inconvenient for setup() (radio packet processing, timer operation, etc.)

Called in re-initialization when the peripheral API is not initialized after returning from sleep.

Called before loop() when waking up from sleep, and includes procedures for initialization after returning from sleep and for branching processing depending on the state of return.

This is the main loop of the application. After the loop ends, the CPU transitions to DOZE mode and waits for the next interrupt with low current consumption.

In the Act description, most of the processing is described in this loop.

It is a base class of packet type, but the member structure common contains address information and other common information.

Called at the beginning of code execution to write initialization code.

After initializing the hardware by the begin() method, the bus can be read and written by beginTransaction(). Executing beginTransaction() selects the SPI select pin. Read/write is done with the transfer() function; SPI reads and writes at the same time.

beginTransaction()

Starts the use of the bus; sets the SPI select pin.

If called with the settings parameter given, the bus is set.

endTransaction()

Terminates the use of the bus; releases the SPI select pin.

transfer(), transfer16(), transfer32()

Reads and writes the bus. transfer() transfers 8 bits, transfer16() transfers 16 bits, and transfer32() transfers 32 bits.

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

The acts starting with act0 are the ones introduced in Starting an act - Opening act, and although they are simple, we recommend you try them out first.

Determines the type of packet using the packet data byte sequence as input. The return value is E_PKT.

E_PKT identify_packet_type(uint8_t* p, uint8_t u8len)

If the packet cannot be interpreted as a specific packet, E_PKT::PKT_ERROR is returned.

Specified as a template argument of a container class (smplbuf, smplque) to allocate or specify an area of memory to be used internally.

In alloc_attach and alloc_heap, initialization methods (init_???()) must be executed according to the memory allocation class.

initialization

void attach(T* p, int n) // alloc_attach
void init_local()        // alloc_local
void init_heap(int n)    // alloc_heap

Initialize with buffer p and size n.

Methods

alloc_size()

uint16_t alloc_size()

Returns the size of the buffer.

_is_attach(), _is_local(), _is_heap()

This method is used to generate a compile error, like static_assert, for a method call description that is different from the expected alloc class.

Flush the output buffer of mwx::stream. Instance to a helper class that calls the flush() method.

for (int i = 0; i < 127; ++i) {
    Serial << "hello world! (" << i << ")" << twe::endl << twe::flush;
}

• For serial ports, wait polling until output completes.

• For mwx::simpbuf buffers, output 0x00 at the end (size is not changed)

This is a callback function that describes the application. Callback means called by the system (library). The user defines several callback functions to describe the behavior of the system.

The following callback functions are mandatory definitions.

• setup()

• loop()

If no other functions are defined, an empty function that does nothing is linked instead.

Normal callback call sequence

init_coldboot()
  ↓ (TWENET internal processing: Initialization 1)
setup()
  ↓（TWENET internal processing: Initialization 2)
begin() --- First time only
  ↓
loop() <--+
  ↓       |Event processing, behavior processing
CPU DOZE -+

Order of callback invocation on return to sleep

the_twelite.sleep()
  ↓ sleeping...
 
 
init_warmboot()
  ↓ (TWENET internal processing: Initialization 3)
wakeup()
  ↓（TWENET internal processing: Initialization 4)
loop() <--+
  ↓       |Event processing, behavior processing
CPU DOZE -+

The TwePacketAppIO class interprets the standard app serial message (0x81) of App_IO The TwePacketAppIO class is the one that interprets the

class TwePacketAppIO : public TwePacket, public DataAppIO { ... };

Various information in the packet data is stored in DataTwelite after parse<TwePacketIO>() execution.

DataAppIO structure

struct DataAppIO {
		// Serial # of sender
		uint32_t u32addr_src;
		
		// Logical ID of the sender
		uint8_t u8addr_src;

		// Destination logical ID
		uint8_t u8addr_dst;

		// Timestamp at the time of transmission
		uint16_t u16timestamp;

		// Flag for low latency transmission
		bool b_lowlatency_tx;

		// Number of repeat relays
		uint16_t u8rpt_cnt;

		// LQI value
		uint16_t u8lqi;

		// DI status bitmap (DI1,2,3,4,...) in order from LSB
		uint8_t DI_mask;

		// Active (1 if used) bitmap of DI (DI1,2,3,4,...) in order from LSB
		uint8_t DI_active_mask;
		
		// Bitmap of whether DI is interrupt-derived or not (DI1,2,3,4,...) in order from LSB
		uint16_t DI_int_mask;
};

Receives incoming packets.

void on_rx_packet(mwx::packet_rx& pkt, bool_t &b_handled) 

When a wireless packet is received, this function is called from within the MWX library with the data stored in pkt as packet_rx. If this function is not defined in the application, a weak function that does nothing is linked.

Setting b_handled to true in this function tells the MWX library that the incoming packet has been processed in the application. If set to processed', it suppresses unnecessary processing. (Do not process the_twelite.receiver`)

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)

Act_samples
  +-PingPong
    +-PingPong.cpp   : ACT file
    +-build          : build dir
    +-.vscode        : setting fils for VSCode    

Copy this PingPong folder to another location (but without Japanese characters or spaces in the folder name).

SomeDir
  +-AlphaBravo
    +-PingPong.cpp -> AplhaBravo.cpp (Note: Changed file name)
    +-build          : build dir
    +-.vscode        : setting files for VSCode

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.

See Makefile Description for how to edit the file.。

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.

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.

• Enviromnents for TWELITE STAGE SDK

• Installing TWELITE STAGE SDK

• (Optional) Installing Visual Stdio code

• Building ACT

• Create a new project

• Makefile

• Use part of MWX code at another platoform(e.g. stdio environment)

Sets the DIO (general-purpose digital IO) pin.

void pinMode(uint8_t u8pin, E_PIN_MODE mode)

This function allows you to change the state of DIO0..19 and the pins DO0,1. The setting contents are described in the enumeration value of E_PIN_MODE, description of DIO and Description of DO.

The uint8_t type smplbuf_strm_u8?? is also available in the stream(stream) interface, so several methods for streams can be used.

// smplbuf_strm_u8<N> : locally allocated
template <int N> using smplbuf_strm_u8 
  = _smplbuf_stream<uint8_t, mwx::alloc_local<uint8_t, N>>;

// smplbuf_strm_u8_attach : attach to an existing buffer
using smplbuf_strm_u8_attach 
  = mwx::_smplbuf_stream<uint8_t, mwx::alloc_attach<uint8_t>>;

// smplbuf_strm_u8_heap : allocate at HEAP
using smplbuf_strm_u8_heap 
  = mwx::_smplbuf_stream<uint8_t, mwx::alloc_heap<uint8_t>>;

// definition of operator <<
template <class L_STRM, class ALOC>
mwx::stream<L_STRM>& operator << (
        mwx::stream<L_STRM>& lhs, 
        mwx::_smplbuf_stream<uint8_t, ALOC>& rhs)
{
		lhs << rhs.to_stream();
		return lhs;
}

Example

smplbuf_strm_u8<128> sb1;

sb1 << "hello";
sb1 << uint32_t(0x30313233);
sb1 << format("world%d",99);
sb1.printfmt("Z!");

Serial << sb1;
// hello0123world99Z!

Detects changes in digital inputs. This class detects changes when the same detected value is obtained multiple times. This is useful for reducing the effect of chattering on mechanical buttons.

Methods

setup()

void setup(uint8_t max_history);

The parameter max_history is the maximum number of references that can be set with begin(). Memory is allocated and initialized here.

begin()

void begin(uint32_t bmPortMask,
				   uint8_t u8HistoryCount,
				   uint16_t tick_delta);

Starts the Buttons operation, the first parameter bmPortMask specifies the bitmap of digital inputs to be monitored. bit 0 corresponds to DIO 0, ... , bit N corresponds to DIO N. More than one can be specified: the second u8HistoryCount is the number of times required to confirm the value; the third tick_delta specifies the interval in ms between value checks; the fourth u8HistoryCount is the number of times to confirm the value.

It will take u8HistoryCount*tick_delta[ms] to confirm the value. For example, if u8HistoryCount=5 and tick_delta=4, it will take at least 20ms to confirm the state.

The confirmation is done in the TickTimer event handler. Since it is not an interrupt handler, it is affected by delays in processing, etc., but it is sufficient to suppress chattering of mechanical buttons, etc.

end()

void end()

Terminates the Buttons operation.

available()

inline bool available()

Returns true when a change is detected. It is cleared when read() is executed.

read()

bool read(uint32_t& u32port, uint32_t& u32changed)

Called when u32port becomes available. u32portis the bitmap of the current input DIO andu32changed` is the bitmap of the DIO where the change was detected.

Returns false if Buttons is not working.

About operation

Initial value determination

When Buttons starts to operate, the input status of DIO is not yet determined. When the value is determined, it becomes available. At this time, the MSB (bit31) of the bitmap read by read() is set to 1.

Since this function requires the operation to be determined, it cannot be used to monitor ports whose input values change constantly.

Sleep

If Buttons is in operation before Sleep, it will resume after it is restored. After resumption, initial determination is performed.

Wait for time by polling (specified in μsec).

void delayMicroseconds(uint32_t microsec)

Wait for a given period of time in microsec.

The time is measured by the TickTimer count. When waiting for a long time, the CPU clock is reduced and polling is performed.

Generates an random number.

uint32_t random(uint32_t maxval)
uint32_t random(uint32_t minval, uint32_t maxval)

The first line returns the value of 0.. (maxval-1) value is returned. Note that the value of maxval is not the maximum value.

The second line returns the value of minval..maxval-1.

This built-in class is defined as a built-in object, intended to be used for format input via serial port.

It is defined as a mwx::serial_parser<mwx::alloc_heap<uint8_t>> type that allocates buffer space for internal use from the heap at initialization (begin()).

For details, see class serparser for details.

Reads the values of all ports in the input settings at once.

uint32_t digitalReadBitmap()

The values are stored in the order of DIO0 ... DIO19 from the LSB side. DIO19 are stored in this order.

The pins on the HIGH side are set to 1 and the pins on the LOW side are set to 0.

Reads the value of the port of the input configuration.

static inline E_PIN_STATE digitalRead(uint8_t u8pin)

Get the input value of a pin that has been previously set as an input, either LOW or HIGH.

The sample in is slightly modified so that the waiting time (approx. 50 ms) during sensor data acquisition is replaced by a sleep wait.

Explanation of ACT

begin()

The begin() function exits the setup() function (after which TWENET is initialized) and is called just before the first loop().

The first sleep is performed after setup() ends. Although sensor data acquisition is started during setup(), this result is not evaluated and is not necessarily necessary, since it means that the sensor is run once in advance.

wakeup()

Procedures after waking up. The following process is performed.

• If the sensor data acquisition start has not yet been performed, the sensor data acquisition is performed and a short sleep is entered.

• Since the start of sensor data acquisition was performed immediately before, the data is checked and sent wirelessly.

The above branch is controlled by the global variable b_sensor_started. If !b_sensor_started, it starts acquiring a sensor (startSensorCapture()) and goes into a short sleep by napNow(). The time is 100ms.

After returning from sleep by napNow(), the clause b_sensor_started==true is executed. Here, the E_EVENT_START_UP event is notified to the two sensors. This event means that enough time has passed for the sensors to finish acquiring. Based on this notification, sns_LTR308ALS and sns_SHTC3 are made available. After this, it will go to loop() and wireless packets will be sent.

napNow()

Perform a very short sleep.

If the second parameter of sleep is set to true, the next wake-up time is adjusted based on the previous sleep wake-up time. This is useful if you always want to wake up every 5 seconds.

If the third parameter is set to true, the sleep mode is set without memory retention. After waking up, wakup() will not be called and the process will be the same as power-on.

The fourth specifies the use of the second wake-up timer. Here, the first is used for normal sleep and the second is used for short sleep. There is no strong reason to use the second timer in this ACT, but if, for example, the user wants to wake up every 5 seconds as described above, using the first timer for a short sleep would reset the counter value, which would complicate the elapsed time correction calculation, so the second timer is used.

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

• - PATH must be set so that the code command can be executed.

Installing plug-ins

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

• C/C++ for Visual Studio Code

Notes

API return value class that wraps 32-bit type. MSB (bit31) is a flag for failure or success. bit0..30 is used to store the return value.

constructor

The default constructor is constructed with a combination of false and 0.

It can also be explicitly constructed with bool and uint32_t types as parameters.

Since the constructor of type bool is implemented, you can use true/false as follows.

Methods

is_success(), operator bool()

Return true if 1 is set in MSB.

Return true if MSB is 0.

Obtain the value part of bit0..30.

Corresponds to the following packet

The TwePacketTwelite class is a standard application , which is an interpretation of the TwePacketTwelite class.

Various information in the packet data is stored in DataTwelite after parse<TwePacketTwelite>() is executed.

DataTwelite structure

Operators and methods by via a that references a smplbuf array of type uint8_t.

Helper object type names are resolved by auto&& because they are long. The interfaces defined in mwx::stream, such as << operator, can be used for this object.

The generated helper object bs starts reading/writing from the beginning of the main array b when it is created. If it is at the end of the array, data is added by append(). Each time a read/write operation is performed, the position is moved to the next one.

Helper functions can use the >> operator for reading.

The timer has two functions: to generate a software interrupt at a specified period, and to output a PWM at a specified period. 5 timers in total are available in the TWELITE radio module, from 0...4.

The name of the built-in object is Timer0..4, but will be referred to as TimerX on this page.

Methods

setup()

Initializes the timer. This call allocates the necessary memory space.

begin()

Starts a timer; the first parameter is the period of the timer in Hz; setting the second parameter to true enables software interrupts; setting the third parameter to true true` enables PWM output.

end()

Stops the timer operation.

available()

It becomes true at loop() immediately after a timer interrupt occurs, and becomes false when loop() ends.

change_duty()

Set the duty ratio. the first parameter specifies the duty ratio (a small value makes the average of the waveform closer to the GND level, a large value makes it closer to the Vcc level). the second parameter specifies the maximum duty ratio value of the duty ratio.

change_hz()

Sets the frequency of the timer; the second parameter is an integer with three decimal places for the frequency. For example, to set the frequency to 10.4 Hz, specify hz=10, mil=400.

Called when transmission is complete.

This function is called from within the MWX library with data stored in ev as packet_ev_tx when the wireless packet transmission is finished. If this function is not defined in the application, a weak function that does nothing is linked.

ev.u8CbId is the ID at the time of transmission and ev.bStatus is a flag indicating success (1) or failure (0) of the transmission.

Setting b_handled to true in this function tells the MWX library that the incoming packet has been processed in the application. If set to processed, it suppresses unnecessary processing. (Do not call event callback functions for the_twelite.app, .board, or .settings)

Waiting for time by polling.

The program waits for a given period of time in ms.

The time is measured by the TickTimer count. When waiting for a long period of time, the CPU clock is decreased and polling is performed.

TickTimer is used for internal control of TWENET and is implicitly executed. The period of the timer is 1ms. Only the available() method is defined in loop() for the purpose of describing processing every 1ms by the TickTimer event.

Methods

available()

It is set after the TickTimer interrupt occurs and becomes true in the loop() immediately following it. It is cleared after loop() ends.

The pulse counter is a circuit that reads and counts pulses even when the microcontroller CPU is not running. There are two systems of pulse counters: PC0 is assigned to PulseCounter0 and PC1 to PulseCounter1.

PC0 is assigned to PulseCounter0 and PC1 is assigned to PulseCounter1.

method

begin()

void begin(uint16_t refct = 0, 
           E_PIN_INT_MODE edge = PIN_INT_MODE::FALLING,
           uint8_t debounce = 0)

Initializes the object and starts counting. the first parameter refct is the count number on which interrupts and available decisions are based. When this number is exceeded, it is reported to the application. You can also set refct to 0. In this case, it is not a sleep wake-up factor.

The second parameter edge specifies whether the interrupt is rising (PIN_INT_MODE::RISING) or falling (PIN_INT_MODE::FALLING).

The third debounce takes the values 0, 1, 2, or 3. 1, 2, or 3 settings require the same consecutive value to detect a change in value to reduce the effect of noise.

end()

void end()

Discontinue detection.

available()

inline bool available()

If the specified count (refct in begin()) is 0, true is returned when the count exceeds 1.

If the specified count (refct in begin()) is 1 or more, true is returned when the number of detections exceeds the specified count.

read()

uint16_t read()

Reads the count value. Resets the count value to 0 after reading.

Reads and writes two-wire serial (I2C) master.

Alias Definition

using TwoWire = mwx::periph_twowire<MWX_TWOWIRE_RCVBUFF>;

The mwx::periph_wire<MWX_TWOWIRE_RCVBUFF> can be referred as TwoWire.

Type Definitions

The following definition types describe the types of arguments and return values.

typedef uint8_t size_type;
typedef uint8_t value_type;

hint style="warning %}

Initialization and termination

Wire Instance Creation

Instance creation and necessary initialization is done in the library. In user code, it is made available by calling Wire.begin().

When using the requestFrom() method, you can specify the size of the FIFO queue for temporary data storage. At compile time, compile the macro MWX_TWOWIRE_BUFF with the required number of bytes. The default is 32 bytes.

Example: -DMWX_TWOWIRE_BUFF=16

begin()

void begin(
    const size_type u8mode = WIRE_100KHZ,
    bool b_portalt = false)

Initialize hardware.

Example

void setup() {
    ...
    Wire.begin();
    ...
}

void wakeup() {
    ...
    Wire.begin();
    ...
}

Reading and Writing

There are two types of read/write procedures. Select and use one of them.

• Member function (input/output using the following member functions) requestFrom(), beginTransmission(), endTransmission(), write()

• Helper class (stream function available) reader, writer

Others

Probe（Determine presence of device)

bool probe(uint8_t address)

Checks if the device specified by address is responding. If the device exists, true is returned.

setClock()

void setClock(uint32_t speed)

The procedure is originally intended to change the bus frequency, but no action is taken.

Reads and writes the SPI bus (as Controller).

Constants

Initialization and termination

The procedure for using the SPI bus depends on the begin() method.

Reads and writes the SPI bus (MASTER).

begin()

void begin(uint8_t slave_select, SPISettings settings)
SPISettings(uint32_t clock, uint8_t bitOrder, uint8_t dataMode)

Initialize hardware.

Example

void setup() {
  ...
  SPI.begin(0, SPISettings(2000000, SPI_CONF::MSBFIRST, SPI_CONF::SPI_MODE3));
  ...
}

void wakeip() {
  ...
  SPI.begin(0, SPISettings(2000000, SPI_CONF::MSBFIRST, SPI_CONF::SPI_MODE3));
  ...
}

end()

void end()

Terminate the use of SPI hardware.

Reading and Writing

There are two types of read/write procedures. Select and use one of them.

• Member function version (input/output using the following member functions) beginTransaction(), endTransaction(), transfer(), transfer16(), transfer32()

• Helper class version (stream function available) transceiver

Implement mwx::stream and input/output with UART0 of TWELITE.

• The Serial object is initialized at system startup with UART0, 115200 bps, and the initialization process is performed in the library. On the user code, it is available from setup().

• The Serial1 object is provided in the library, but no initialization process is performed; to enable UART1, perform the necessary initialization procedures Serial1.setup(), Serial1.begin().

setup()

void setup(uint16_t buf_tx, uint16_t buf_rx)

Initialize objects.

• Allocate memory for FIFO buffers for TX/RX

• Allocating memory for TWE_tsFILE structure

begin()

void begin(unsigned long speed = 115200, uint8_t config = 0x06)

Initialize hardware.

end()

(Not implemented) Stop using hardware.

get_tsFile()

TWE_tsFILE* get_tsFile();

Get a structure in the TWE_tsFILE* format used in the C library.

pktparser(parser_packet) performs content interpretation on the byte sequence converted by serparser performs content interpretation on the byte sequence converted by serparser.

serparser_heap parser_ser;

void setup() {
    // init ser parser (heap alloc)
    parser_ser.begin(PARSER::ASCII, 256);
}

void loop() {
    int c;
    while ((c = Serial.read()) >= 0) {
        parser_ser.parse(c);
        if (parser_ser.available()) {
            // get buffer object
            auto&& payl = parser_ser.get_buf();
            // identify packet type
            auto&& typ = identify_packet_type(payl.begin(), payl.end());
            
            // if packet type is TWELITE standard 0x81 message
            if (typ == E_PKT::PKT_TWELITE) {
                pktparser pkt; // packet parser object
                // analyze packet data
                typ = pkt.parse<TwePacketTwelite>(payl.begin(), payl.end());
                
                if (typ != E_PKT::PKT_ERROR) { // success!
                    // get data object
                    auto&& atw = pkt.use<TwePacketTwelite>();
                    
                    // display packet inforamtion
                    Serial << crlf << format("TWELITE: SRC=%08X LQI=%03d "
                        , app.u32addr_src, app.u8lqi);
	                  Serial << " DI1..4="
	                      << atw.DI1 ? 'L' : 'H' << atw.DI2 ? 'L' : 'H' 
                        << atw.DI3 ? 'L' : 'H' << atw.DI4 ? 'L' : 'H';
                }
            }
        }
    }
}

The above example interprets standard application 0x81 message. parser_ser object converts the message input from Serial into a byte string. This byte string is first identified by identify_packet_type() to determine the type of the message E_PKT. Once the message type is determined, the message is parsed by .parse<TwePacketTwelite>(). The parsed result will be of type TwePacketTwelite, and .use<TwePacketTwelite>() is the procedure to extract this object. The TwePacketTwelite type is a class, but it refers to its member variables directly as a structure.

parse<T>

template <class T>
E_PKT parse(const uint8_t* p, const uint8_t* e)

Parses a sequence of bytes.

The T specifies the packet type to be parsed. For example, TwePacketTwelite is specified for 0x81 messages in standard applications.

p and e specify the next to the beginning and the end of the byte sequence.

The return value is of type E_PKT. In case of an error, E_PKT::PKT_ERROR is returned.

user<T>

template <class T> 
T& use()

Returns a reference to an object corresponding to the packet type of the interpreted byte sequence. It can be called if parse<T> was executed beforehand and there were no errors.

The T can be the same type as the one executed with parse<T>, or a TwePacket from which only basic information can be obtained.

Enables DIO interrupts.

void attachIntDio(uint8_t u8pin, E_PIN_INT_MODE mode)

For a preconfigured pin, the first parameter is the pin number for which you want to enable interrupts, the second is the interrupt direction (rising, falling.

Example

Set up an interrupt to be generated when the DIO5 pin changes from HIGH to LOW.

void setup() {
  the_twelite.app.use<myAppClass>();
  
  pinMode(PIN_DIGITAL::DIO5, PIN_MODE::INPUT_PULLUP);
  attachIntDio(PIN_DIGITAL::DIO5, PIN_INT_MODE::FALLING);
}

void loop() {
  ;
}

myAppClass.hpp

class myAppClass: public mwx::BrdPal, MWX_APPDEFS_CRTP(myAppClasslMot)
{

};

Basic definition of the application behavior myAppClass. Details are omitted.

myAppClass.cpp

/*****************************************************************/
// MUST DEFINE CLASS NAME HERE
#define __MWX_APP_CLASS_NAME myAppClass
#include "_mwx_cbs_cpphead.hpp"
/*****************************************************************/

MWX_DIO_INT(PIN_DIGITAL::DIO5, uint32_t arg, uint8_t& handled) {
  static uint8_t ct;
  digitalWrite(PIN_DIGITAL::DIO12, (++ct & 1) ? HIGH : LOW);
	handled = false; // if true, no further event.
}

MWX_DIO_EVENT(PIN_DIGITAL::DIO5, uint32_t arg) {
  Serial << '*';	
}

/*****************************************************************/
// common procedure (DO NOT REMOVE)
#include "_mwx_cbs_cpptail.cpp"
// MUST UNDEF CLASS NAME HERE
#undef __MWX_APP_CLASS_NAME
} // mwx
/*****************************************************************/

Description of the interrupt handler of the application behavior myAppClass, which inverts the output setting of DIO12 when an interrupt of DIO5 is generated and displays * on the serial port Serial for events occurring after the interrupt handler is finished.

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

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.

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

pulse counter is an example of an ACT.

The pulse counter counts the number of rising or falling pulses of a signal without intervening microcontroller. It can be used to count irregular pulses and send wireless packets when the count reaches a certain number of times.

Function of ACT

• Counts the pulses connected to DIO8 on the Child Node side and transmits them wirelessly after a certain period of time or when a certain number of counts are detected.

• The Child Node side operates while sleeping.

How to use ACT

Required TWELITE

Explanation of ACT

setup()

// Pulse Counter setup
PulseCounter.setup();

Initializes the pulse counter.

begin()

void begin() {
	// start the pulse counter capturing
	PulseCounter.begin(
		  100 // 100 count to wakeup
		, PIN_INT_MODE::FALLING // falling edge
		);

	sleepNow();
}

Starts the pulse counter operation and performs the first sleep. The first parameter of PulseCounter.begin() is the count number 100 to generate a wake-up interrupt, and the second is the falling detection PIN_INT_MODE::FALLING.

wakeup()

void wakeup() {
	Serial	<< mwx::crlf
			<< "--- Pulse Counter:" << FOURCHARS << " wake up ---"
			<< mwx::crlf;

	if (!PulseCounter.available()) {
		Serial << "..pulse counter does not reach the reference value." << mwx::crlf;
		sleepNow();
	}
}

Checks PulseCounter.available() when waking up. available, that is, true, indicates that the count is greater than or equal to the specified count. If it is false, it resleeps.

If the count is more than the specified number, loop() processes the transmission and waits for the completion of the transmission.

loop()

uint16_t u16ct = PulseCounter.read();

Reads the pulse count value. The counter is reset after the readout.

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.

Other updates to the MWSDK may be required. Please refer to the release description at the time of the update; see for information on updating the MWSDK.

Updating MWX library code

The source code of the library is available on GitHub (). To replace the source code of the library, please follow the steps below.

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

• added (At this time, only Parent Node reception is supported.)

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

• added to describe placement new simply.

• added support of

  • 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 board support for TWELITE ARIA and sensor definition

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

• Added event callbacks to notify received packets () and completed transmission ().

  • 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 board behavior () for TWELITE CUE.

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

• Add EEPROM class object. ()

  • Samples ()

• Fixed bugs in smplbuf::get_stream_helper().

• Added pktparser class ()

  • Added sample ()

• sample serparser/pktparser so that it can be built on other platforms ()

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.

• Added NOTICE PAL / PCA9632 support (Description , sample )

• 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

• Added

• Channel Manager. Implement

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)

WirelessUART performs serial communication.

ACT Features.

• Communicate between two UART-connected TWELITEs in ASCII format.

how to use act

Required TWELITE

Two of the following devices serially connected to a PC.

• connected to UART with products/TWE-Lite-DIP/index.html) etc.

Explanation of ACT

setup()

Interactive settings mode is initialized. This sample provides two or more devices that have different logical device IDs (LIDs) from each other.

Initialize .

loop()

When data input from the serial is received, one byte is input to the serial parser. When the ASCII format is accepted to the end, SerialParser.parse() returns true.

The SerialParser can access the internal buffer with smplbuf. In the example above, the first byte of the buffer is taken as the destination address, and the second byte to the end is passed to the transmit() function.

on_rx_packet()

When a packet is received, a buffer smplbuf_u8<128> buf containing the payload followed by the source as the first byte is created and output serially from the serial parser serparser_attach pout for output.

command for testing

example

Send 00112233 to any Child Node.

example

Send AABBCC00112233 to Child Node #3.

example

Sent to any Parent Node or Child Node (0xFF) and to the Parent Node (0x00).

TWELITE Reads and writes to the built-in EEPROM of the wireless microcontroller.

The built-in EEPROM has 3480 bytes available from address 0x000 to 0xEFF.

The first part is , so it is recommended to use the second half of the address when used together. The amount of space consumed by the settings (Interactive settings mode) depends on its implementation. Even with minimal settings, up to 256 bytes are used from the beginning, so use of the later addresses is recommended.

Methods

read()

Read the data corresponding to address from EEPROM.

write()

Write value from EEPROM to address.

update()

This function is used when you want to reduce the number of rewrites in consideration of the rewrite life of EEPROM.

get_stream_helper()

Obtain a helper object to read and write using mwx::stream described below.

mwx::streamインタフェースを用いた入出力

operators and methods. Using mwx::stream, you can read and write integer types such as uint16_t and uint32_t types, read and write fixed-length array types such as uint8_t, and format them using format() objects.

Interfaces defined in mwx::stream, such as the << operator, can be used on this object.

.seek() is used to move the EEPROM address to 1024.

The above writes an 8-byte string (00bc614e), a 4-byte integer (0x12ab34cd), a 16-byte byte string (HELLO WORLD!.... ), and a 1-byte terminating character.

Move the EEPROM address to 1024 using .seek().

Reads the data sequence written out earlier. In order, 8-byte characters, 4-byte integers, and 16-byte strings are read out using the >> operator.

This class is a wrapper class for TWENET's tsRxDataApp structure.

This class object is a wrapper class for callback function or by .

In packet_rx, in particular, the data payload of the packet can be handled by the smplbuf container, and utility functions such as expand_bytes() simplify the payload interpretation description.

Methods

get_payload()

Get the data payload of the packet.

get_psRxDataApp()

Obtain the receiving structure of the TWENET C library.

get_length()

Returns the data length of the payload. The value is the same as .get_payload().size().

get_lqi()

Obtain the LQI value (Link Quality Indicator).

get_addr_src_long(), get_addr_src_lid()

Get the address of the sender.

get_addr_src_long() is the serial number of the sender and MSB(bit31) is always 1.

get_addr_src_lid() is the logical ID of the sender and takes values from 0x00-0xFE (the logical ID specified by <NWK_SIMPLE>).

get_addr_dst()

Gets the destination address.

The destination address is specified by the source, and the range of values varies depending on the type of destination.

is_secure_pkt()

Returns true for encrypted packets and false for plaintext.

get_network_type()

Returns network type of the packet identified by Network BEHAVIOR.

The method using member functions has a relatively low level of abstraction and follows the general API system as provided by the C library. The procedures for operating the two-wire serial bus are more intuitive.

However, it is necessary to be explicitly aware of the start and end of bus usage.

Read

requestFrom()

Reads the specified number of bytes at once. Since the result of reading is stored in a queue, call the .read() method immediately afterward until the queue is empty.

Code Example

Writing

Writing is performed by the write() method after executing beginTransmission(). Call endTranmission() after a series of writing is finished.

beginTransmission()

Initialize the export transfer. Call endTransmission() as soon as the writing process is finished.

write(value)

Writes one byte.

write(*value, quantity)

Writes a byte sequence.

endTransmission()

Processes the end of the export.

The helper class version is a more abstract implementation. Creating a transceiver object for reading and writing is the start of using the bus, and destroying the object is the end of using the bus.

By creating the object in the decision expression of the if statement, the validity period of the object is limited to the scope of the if clause, and the object is destroyed when it exits the if clause, at which point the bus usage termination procedure is performed.

In addition, read/write objects implement the mwx::stream interface, allowing the use of the << operator, etc.

• The start and end of bus usage is aligned with the validity period of the object to improve the visibility of the source code and to prevent omissions in the termination procedure, etc.

• Unify read/write procedures with the mwx::stream interface

read/write

Reading process and its termination procedure in scope if() { ... } to do the reading with a helper class.

In the above, the x object created by the get_rwer() method is used to read and write one byte at a time. 1.

1. create x object in if(...) Generate the x object in the get_rwer() method. At the same time, set the select pin of the SPI bus. (The type is resolved with the universal reference auto&& by type inference. 2.)

2. the generated x object has a operator bool () defined, which is used to evaluate the decision expression, which is always true for the SPI bus.

3. x object defines uint8_t transfer(uint8_t) method, which is called to perform 8bit read/write transfer to SPI. 4. 4.if() { ... } Destructor of x is called at the end of the scope to release the select pin of the SPI bus.

get_rwer()

Obtains the worker object used to read/write the SPI bus.

worker object

transfer() transfer16() transfer32()

Each transfers 8-bit, 16-bit, and 32-bit data, and returns the read result with the same data width as the written data width.

<< operator

The int and uint8_t types perform 8-bit transfer.

Types uint16_t and uint32_t perform 16-bit and 32-bit transfers, respectively.

The transfer result is stored in an internal FIFO queue of up to 16 bytes and read by the >> operator. Since the buffer is not large, it is assumed to be read out after each transfer.

>> operator

Specify a variable with the same data width as the previous transfer.

If the result of the read is not needed, use the null_stream() object; it skips reading by the data byte specified by i. If the result of the read is not needed, use the null_stream() object.

This structure is used to store the values of 3-axis accelerometers, but procedures have been added to increase convenience when stored in a container class.

get_axis_{x,y,z}_iter()

Generates an iterator that accesses an element on the X, Y, or Z axis using the iterator of the container class containing axis_xyzt as a parameter.

In the example below, buf.begin() and buf.end() are used as iterators for the X axis in the algorithm std::minmax_element.

get_axis_{x,y,z}()

This function generates a virtual container class from which one of the XYZ axes of the container class containing axis_xyzt is taken. Only the begin() and end() methods are implemented in this generated class. The iterator that can be obtained by these begin() and end() methods is the same as the iterator in the previous section .

The TwePacketAppUart class is the format in which the extended format of the App_UART is received by the parent and repeater application App_Wings.

Various information in the packet data is stored in DataAppUART after parse<TwePacketUART>() execution.

DataAppUART structure

The payload is the data part, but the method of data storage changes depending on the macro definition.

If MWX_PARSER_PKT_APPUART_FIXED_BUF is compiled with the value 0, payload refers directly to the byte sequence for packet analysis. If the value of the original byte sequence is changed, the data in payload will be destroyed.

If you define the value of MWX_PARSER_PKT_APPUART_FIXED_BUF to be greater than 0, the payload will allocate a buffer of that value (bytes). However, if the data of the serial message exceeds the buffer size, parse<TwePacketAppUART>() fails and returns E_PKT::PKT_ERROR.

Helper class for writing format format to the << operator of mwx::stream. In the library, it is alias defined as Using format=mwx::mwx_format;.

• Store the argument list received in the constructor in a variable internal to the class using the expand function of the parameter pack.

• Call fctprintf() at the point operator << is called to write data to the stream

Constructor

The constructor stores the format pointer and parameters. The subsequent call with the << operator interprets the format and processes the output.

This class is a wrapper class for the tsTxDataApp structure of the TWENET C library, and objects of derived classes based on this class are obtained from network behaviors or on_tx_comp().

if (auto&& pkt = the_twelite.network.use<NWK_SIMPLE>().prepare_tx_packet()) {
	pkt << tx_addr(0x00)
		<< tx_retry(0x1)
		<< tx_packet_delay(0,50,10);
		
	pack_bytes(pkt.get_payload()
		, make_pair("APP1", 4)
		, uint8_t(u8DI_BM)
	);
  
  pkt.transmit();
}

Generating objects

This is done by the network behavior .prepare_tx_packet().

if (auto&& pkt = the_twelite.network.use<NWK_SIMPLE>().prepare_tx_packet()) {
  ...
}

In the above example, the_twelite.network.use<NWK_SIMPLE>() retrieves an object of the network behavior. The object pkt is created by .prepare_tx_packet() of this object. It is a derived class of packet_tx, although the type name is inferred by auto&&.

This pkt object first returns true or false in the if(). A false return occurs when the queue for sending is full and no more requests can be added.

Transmission Settings

Various settings are configured in the radio packet to deliver the packet to the destination, including destination information. To configure the settings, an object containing the settings is given as the right-hand side value of the << operator.

pkt << tx_addr(0x00)
	  << tx_retry(0x1)
  	<< tx_packet_delay(0,50,10);

The following is a description of the objects used for configuration.

tx_addr

tx_addr(uint32_t addr)

Specify the destination address addr. See the Network Behavior specification for the destination address value.

• <NWK_SIMPLE> An address set with an MSB (bit31=0x80000000) means that it is addressed to the serial number of the radio module. 0x00. 0xFE means that the address is addressed to the child module (0x01...0xEF). 0xFE means broadcast to the child (0x01...0xEF), and 0xFF` means broadcast to both the parent and the child.

tx_retry

tx_retry(uint8_t u8count, bool force_retry = false)

Specifies the number of retransmissions. The number of retransmissions is specified by u8count. force_retry is a setting to retransmit a specified number of times regardless of whether the transmission is successful or not.

• <NWK_SIMPLE> ネットワークビヘイビア<NWK_SIMPLE>では、同じ内容のパケットをu8count+1回送信します。 force_retryの設定は無視されます。

tx_packet_delay

tx_packet_delay(uint16_t u16DelayMin,
                uint16_t u16DelayMax,
                uint16_t u16RetryDur)

Sets the delay between sending packets and the retransmission interval. Specify two values, u16DelayMin and u16DelayMax, in milliseconds [ms]. Transmission will be started at some point during this interval after a transmission request is made. Specify the retransmission interval as the value of u16RetryDur in milliseconds[ms]. The retransmission interval is constant.

• <NWK_SIMPLE> This specification is valid.

tx_process_immediate

tx_process_immediate()

This setting requests that packet transmission be performed "as quickly as possible." Packet transmission processing in TWENET is performed from the TickTimer, which runs every 1 ms. By setting this parameter, the packet transmission request is processed as soon as possible after the request is made. Of course, any setting other than tx_packet_delay(0,0,0) is a meaningless specification.

If other packet transmission processing is in progress, it will be processed as usual.

• <NWK_SIMPLE> This designation is valid.

tx_ack_required

tx_ack_required()

In wireless packet communications, there is a transmission method in which a short radio message called ACK (ACK) is obtained from the destination after the transmission is completed to indicate that the transmission was successful. By setting this option, transmission with ACK is performed.

• <NWK_SIMPLE>

tx_addr_broadcast

tx_addr_broadcast()

Specify broadcast.

• <NWK_SIMPLE>

Specify the destination address tx_addr(0xFF) (broadcast) or tx_addr(0xFE) (broadcast to the child) instead.

tx_packet_type_id

tx_packet_type_id(uint8_t)

Specify the type ID of the TWENET radio packet that can be 0..7.

• <NWK_SIMPLE>

`` uses type ID internally. Users cannot use it.

stream_helper is a helper object that grants the mwx::stream interface. It creates a helper object that references a data class and performs data input/output via the helper object.

The following creates a helper object bs from an array b of smplbufs and inputs data using the mwx::stream::operator <<() operator.

smplbuf_u8<32> b;
auto&& bs = b.get_stream_helper(); // helper object

// Data String Generation
uint8_t FOURCHARS[]={'A', 'B', 'C', 'D'};
bs << FOURCHARS;
bs << ';';
bs << uint32_t(0x30313233); // "0123"
bs << format(";%d", 99);

Serial << b << crlf; // Output to Serial via smplbuf_u8<32> class

//result: ABCD;0123;99

Overview

stream_helper behaves as if the data array were a stream.

Internally, it holds read/write positions in the data array. It behaves as follows.

• After the last data is read or written, it moves to the next read/write position.

• After the last data is read or data is appended to the end, the read/write position becomes the end.

• If the read/write position is the end of the line, then

  • available() becomes false.

  • Read cannot be performed.

  • Writing is appended if it is within the writable range.

generating stream_helper

stream_helper is a data class (smplbuf, EEPROM) member functions.

auto&& obj_helper = obj.get_stream_helper()
// obj is an object of data class, obj_helper type is accepted by auto&& because it is long.

methods

rewind()

void rewind()

Moves the read/write position to the beginning.

seek()

int seek(int offset, int whence = MWX_SEEK_SET)

Set the read/write position.

tell()

int tell()

Returns the read/write position. Returns -1 for the end position.

available()

int available()

Returns 0 if the read/write position is the end. If it is not the end, it returns any other value.

An ACT (Act) beginning with _Unit_ is used to describe a very single function or to check the operation of a function.

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

• act0..4 is a very simple example, without any radio functions, to give you an idea of the basic structure of Act.

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.

• BRD_I2C_TEMPHUMID

Typical elements for implementing wireless sensors in TWELITE (simple relay net <NWK_SIMPLE>, Interactive settings mode <STG_STD>, I2C sensor handling Wire, intermittent operation with sleep, etc.).

Basic ACT for wireless communication

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

• Scratch is a simple code that receives 1 byte commands from the UART, sends them and so on.

• Slp_Wk_and_Tx uses a state machine and intermittent operation with sleep, repeating the process of sleep recovery, radio transmission and sleep.

• PingPong is a sample of sending packets from one side to the other and receiving packets back by the other side. It contains basic procedures for sending and receiving.

• WirelessUART interprets the UART input into ASCII format using serparser and sends it.

ACT on Parent Node side

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

• Parent_MONOSTICK exclusively receives and outputs the reception result to the serial port. The wireless packets in this sample, which are addressed to the parent device (0x00) or to the child device broadcast (0xFE), can be received. It also includes a procedure to add the interactive mode <STG_STD> to Act.

• Rcv_Univsl is an example code for universal packets receiver (e.g. TWENET layered tree network, App_Twelite, Act, ...). It alse uses EASTL library for container or some algorithm.

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)

• BRD_I2C_TEMPHUMID executes I2C sensor device read/write commands and wirelessly transmits measurements obtained from I2C sensors. It also uses the Interactive settings mode <STG_STD> to Act.

• Setting provides a higher degree of customisation of the interactive mode <STG_STD>.

ACT to operate sensors and other devices

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

• BRD_I2C_TEMPHUMID executes I2C sensor device read/write commands and wirelessly transmits measurements obtained from I2C sensors. It also uses the Interactive settings mode <STG_STD> to Act.

• BRD_APPTWELITE provides bidirectional communication using digital input, analogue input, digital output and analogue output. It also contains the procedure for adding the interactive mode <STG_STD> to Act.

• PulseCounter uses a pulse counter function to count the number of pulses detected on the input port, even during sleep, and to transmit this data wirelessly.

• PAL_AMB_behavior is a behavioural example: in PAL_AMB the temperature and humidity sensors are called by the code inside the library, but this sample also includes its own procedure for accessing the temperature and humidity sensors via I2C bus.

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.

• PAL_AMB

• PAL_MOT-single

• PAL_MAG

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

• PAL_AMB_usenap is a sample that aims to save more power by allowing the TWELITE microcontroller to sleep briefly during the sensor's operating time, which can take several tens of milliseconds.

• PAL_AMB_behavior is a behavioural example: in PAL_AMB the temperature and humidity sensors are called by the code inside the library, but this sample also includes its own procedure for accessing the temperature and humidity sensors via I2C bus.

• PAL_MOT_fifo for continuous acquisition and wireless transmission of samples without interruption, using the accelerometer's FIFO and FIFO interrupts.

ACT, which introduced the stand-alone function

Acts with names starting with Unit are intended to introduce features and APIs.

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";

The TwePacketPal class interprets TWELITE PAL packet data. This class handles TWELITE PAL (sensor data and other upstream data) commonly.

class TwePacketPal : public TwePacket, public DataPal { ... };

PAL common data is defined in DataPal.

Generator functions are provided to retrieve data specific to each PAL sensor board.

DataPal structure

Although the packet data structure of PAL differs depending on the connected sensors, etc., DataPal holds the data structure of the common part.

struct DataPal {
	uint8_t u8lqi; // LQI value

	uint32_t u32addr_rpt; // address of the relay

	uint32_t u32addr_src; // source address
	uint8_t u8addr_src; // source logical address

	uint16_t u16seq; // sequence number

	E_PAL_PCB u8palpcb; // PAL board type
	uint8_t u8palpcb_rev; // Revision of PAL board
	uint8_t u8sensors; // Number of sensor data in the data (MSB=1 is an error)
	uint8_t u8snsdatalen; // sensor data length (in bytes)

	union {
		const uint8_t *au8snsdata; // reference to sensor data part
		uint8_t _pobj[MWX_PARSER_PKT_APPPAL_FIXED_BUF]; // each sensor object
	};
};