the_twelite

Core class for TWENET usage (mwx::twenet)

The the_twelite object consolidates procedures for using TWENET, including basic wireless settings, sleep procedures, and other operations to control the wireless microcontroller.

Overview

the_twelite performs settings and start the_twelite.begin() within the setup() function. Settings cannot be done outside of setup().

void setup() {
  ...
 	the_twelite
		<< TWENET::appid(APP_ID)
		<< TWENET::channel(CHANNEL)
		<< TWENET::rx_when_idle();
  ...
  the_twelite.begin();
}

In the above example, the application ID setting, communication channel setting, and receiver circuit setting are performed.

Various procedures are included.

// Get the serial number
uint32_t u32hwser = the_twelite.get_hw_serial();

// Set channel to 11
the_twelite.change_channel(11);

// Sleep for 1 second
the_twelite.sleep(1000);

// Perform reset
the_twelite.reset_system();

Also, classes that handle wireless networks, board support, and user-written event-driven processing can be registered. By registering these classes, specialized functions can be easily utilized. These classes are referred to as “Behaviors” in this documentation.

void setup() {
	/*** SETUP section */
	// use PAL_AMB board support.
	auto&& brd = the_twelite.board.use<PAL_AMB>();

	...

	// Register Network
	auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();
	nwk << NWK_SIMPLE::logical_id(u8ID);

In the above example, two types are registered: the environmental sensor PAL <PAL_AMB> and the simple relay network <NWK_SIMPLE>. By registering these, hardware such as sensors on the environmental sensor PAL can be easily handled. Also, complicated wireless packet handling such as relay processing and automatic discarding of duplicate packets can be implicitly enabled.

Methods

The MWX library defines methods other than those introduced here.

These include methods unrelated to actor description, those that do not function effectively even if set, and those used internally.

`<<` operator (Settings)

The << operator is used to perform initial settings of the the_twelite object.

The following setting class objects are input, and if not set, default values are applied.

`TWENET::appid(uint32_t id)`

Sets the application ID specified by parameter id. This is mandatory.

Reading the setting is done by uint32_t the_twelite.get_appid().

`TWENET::channel(uint8_t ch)`

Sets the channel number (11..26) specified by parameter ch.

Reading the setting is done by uint8_t the_twelite.get_channel().

`TWENET::tx_power(uint8_t pw)`

Sets the output power setting (0..3) specified by parameter pw. The default is (3: no output attenuation).

Reading the setting is done by uint8_t the_twelite.get_tx_power().

`TWENET::rx_when_idle(uint8_t bEnable)`

If parameter bEnable is 1, the receiver circuit is always active to receive wireless packets from others. The default is 0, meaning mainly transmission only.

Reading the setting is done by uint8_t the_twelite.get_rx_when_idle().

`TWENET::chmgr(uint8_t ch1 = 18, uint8_t ch2 = 0, uint8_t ch3 = 0)`

Enables the channel manager. If multiple channels are specified, transmission and reception are performed on multiple channels. If 0 is specified for ch2 or ch3, that specification is disabled.

`STG_STD`

Applies the Interactive Mode settings.

auto&& set = the_twelite.settings.use<STG_STD>();
...
set.reload();       // Load settings
the_twelite << set; // Apply Interactive Mode settings

The applied items are as follows:

app_id
channel
tx_power
Retransmission count when using MAC ack

There are other setting items in the MWX library code, but as of now, they are either unrelated to library functions or may cause contradictions if set.

`begin()`

void begin()

Execute after completing prior settings (<< operator reference) and behavior registration. Usually placed at the very end of the setup() function.

the_twelite setup completed
Behavior initialization

TWENET initialization is also executed after the setup() function finishes. Since many processes are designed to run after setup() ends, avoid performing anything other than initialization here.

Example

void setup() {
	// use PAL_AMB board support.
	auto&& brd = the_twelite.board.use<PAL_AMB>();

	// settings
 	the_twelite
		<< TWENET::appid(APP_ID)
		<< TWENET::channel(CHANNEL)
		<< TWENET::rx_when_idle();

	// Register Network
	auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();
	nwk << NWK_SIMPLE::logical_id(u8ID);

	// some others

	// begin the TWENET!
	the_twelite.begin();
}

`change_channel()`

inline bool change_channel(uint8_t u8Channel)

Changes the channel setting. If it fails, the channel is not changed and returns false.

`get_channel_phys()`

uint8_t get_channel_phys()

Gets the currently set channel number (11..26). Obtained from the MAC layer API.

`get_hw_serial()`

inline uint32_t get_hw_serial()

Gets the module’s serial number.

`sleep()`

inline void sleep(
        uint32_t u32Periodms,
        bool_t bPeriodic = true,
        bool_t bRamOff = false,
        uint8_t u8Device = TWENET::SLEEP_WAKETIMER_PRIMARY)

Puts the module to sleep.

Parameter	Description
`u32Periodms`	Sleep duration [ms]
`bPeriodic`	Recalculates next wake-up time based on the last wake-up time. ※ Sometimes the next wake-up timing may be from the current time due to proximity.
`bRamoff`	If set to `true`, sleep without retaining RAM (after waking up, reinitialization should start from `setup()` instead of `wakeup()`)
`u8Device`	Specifies the wake-up timer used for sleep. Specify either `TWENET::SLEEP_WAKETIMER_PRIMARY` or `TWENET::SLEEP_WAKETIMER_SECONDARY`.

Before sleep, the on_sleep() method of embedded objects and behaviors is called to perform pre-sleep procedures. After wake-up, the on_wakeup() method is called for recovery processing.

`is_wokeup_by_dio()`

bool is_wokeup_by_dio(uint8_t port)

Returns true if the wake-up cause from sleep is the specified digital pin.

`is_wokeup_by_wktimer()`

bool is_wokeup_by_wktimer()

Returns true if the wake-up cause from sleep is the wake-up timer.

`reset_system()`

inline void reset_system()

Resets the system. After reset, processing starts from setup().

`stop_watchdog()`

inline void stop_watchdog()

Stops the watchdog timer. Stop the timer when performing long polling waits.

The watchdog timer is restarted each time in the library’s main loop. It resets after about 4 seconds if the timer expires.

`restart_watchdog()`

inline void restart_watchdog()

Restarts the watchdog timer.

Behaviors

twe_twelite can register three behaviors, and the following class objects are defined to hold them.

network : Behavior implementing the network. Usually register <NWK_SIMPLE>.
network2 : Behavior implementing the network. Used when you want to process packets rejected by network (due to payload data structure or other criteria) with another network behavior. (Reference: Using NWK_LAYERED and NWK_SIMPLE together)
board: Behavior for board support. Adds procedures for using devices on the board.
app: Behavior describing user applications. Allows writing interrupt or event descriptions and state transitions using state machines. Also allows defining multiple application descriptions and easily selecting completely different applications at startup.
settings: Behavior for executing settings (Interactive Mode). Register <SET_STD>.

`use<B>()`

// Example
auto&& brd = the_twelite.board.use<PAL_AMB>();

Registers behavior <B>. Registration is done inside setup(). The return value is a reference to the object corresponding to the registered behavior.

After registration, the object can be retrieved with the same syntax as during registration.

If an incorrect behavior is specified, a panic operation (infinite loop) occurs and the program stops running.

Declaring behavior objects as global variables is not intended. Use use<B>() each time you use it.

void loop() {
  auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();
}

However, it is possible to define a pointer to the object as a global variable and write as follows. (In MWX library, pointer types are minimized and references are preferred, so such usage is not recommended.)

NWK_SIMPLE *pNwk = nullptr;

setup() {
  auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();
	pNwk = &nwk;
}

void transmit() {
  if (auto&& pkt = pNwk->prepare_tx_packet()) {
    ...
  }
}

Class Objects

the_twelite defines the three class objects board, network, and app mentioned above, and also defines the following.

`tx_status`

Notifies the transmission completion status.

In event-driven behavior descriptions, manage via transmit_complete() callback.

`is_complete()`

bool is_complete(uint8_t cbid)

Returns true when the packet with the specified ID has completed transmission.

`is_success()`

bool is_success(uint8_t cbid)

Returns true when the packet with the specified ID has completed transmission and the transmission was successful.

`receiver`

Obtains received packets.

the_twelite.receiver is not recommended.

Previously, processing using the_twelite.receiver was intended inside loop(), but due to delay processing by queue, packet loss can occur in principle, and the description tends to be complicated. Therefore, on_rx_packet() was added.

In event-driven behavior descriptions, obtain via receive() callback.

The received packet data obtained by the read() method is designed to be overwritten by subsequent packets during reception processing. If you read immediately after available and perform short processing, it is not a problem, but in principle, read → copy necessary data for application → quickly finish loop(). For example, performing long delay() in loop() may cause packet loss.

`available()`

bool available()

Returns true if there is a received packet not yet read.

`read()`

packet_rx& read()

Reads a packet.

the_twelite

Overview

Methods

<< operator (Settings)

TWENET::appid(uint32_t id)

TWENET::channel(uint8_t ch)

TWENET::tx_power(uint8_t pw)

TWENET::rx_when_idle(uint8_t bEnable)

TWENET::chmgr(uint8_t ch1 = 18, uint8_t ch2 = 0, uint8_t ch3 = 0)

STG_STD

begin()

Example

change_channel()

get_channel_phys()

get_hw_serial()

sleep()

is_wokeup_by_dio()

is_wokeup_by_wktimer()

reset_system()

stop_watchdog()

restart_watchdog()

Behaviors

use<B>()

Class Objects

tx_status

is_complete()

is_success()

receiver

available()

read()

`<<` operator (Settings)

`TWENET::appid(uint32_t id)`

`TWENET::channel(uint8_t ch)`

`TWENET::tx_power(uint8_t pw)`

`TWENET::rx_when_idle(uint8_t bEnable)`

`TWENET::chmgr(uint8_t ch1 = 18, uint8_t ch2 = 0, uint8_t ch3 = 0)`

`STG_STD`

`begin()`

`change_channel()`

`get_channel_phys()`

`get_hw_serial()`

`sleep()`

`is_wokeup_by_dio()`

`is_wokeup_by_wktimer()`

`reset_system()`

`stop_watchdog()`

`restart_watchdog()`

`use<B>()`

`tx_status`

`is_complete()`

`is_success()`

`receiver`

`available()`

`read()`