Software Development

• 1: UART Communication Without the STAGE App
• 2: Using Interactive Mode Programmatically

1 - UART Communication Without the STAGE App

When the TWELITE STAGE App is Not Suitable

The Terminal of the TWELITE STAGE app is intended only for simple evaluation purposes. Therefore, for advanced UART communication such as the serial communication app’s format modes (ASCII / Binary), there are the following issues:

• When inputting a sequence to TWELITE’s RX, you must paste a pre-copied string using Alt+V / ⌘+V.
• Binary data cannot be handled in HEX (hexadecimal) notation.

Overview of CoolTerm

CoolTerm is a general-purpose software specialized for serial communication. Unlike TeraTerm, it can handle binary data without using debug mode and supports multiple platforms.

Installation

Please download the files from the author’s homepage.

Configuration

In CoolTerm, you can name the serial port and its associated settings.

Here, we introduce the necessary settings to adapt to the default TWELITE series.

Settings can be changed from the Options menu.

Serial Port

Within Options, under Serial Port, check the following settings:

• Port: The port used by the TWELITE R or MONOSTICK
• Baudrate: Set to 115200 bps

Terminal

Within Options, under Terminal, mainly check the following settings:

• Terminal Mode: Raw Mode
• Enter Key Emulation: CR+LF

Data Handling

Within Options, under Data Handling, mainly check the following settings:

• Clear Display on: Check ESC[2J] (enables screen clearing in interactive mode)
• Check Handle BS and DEL Characters (enables character deletion in interactive mode)
• Text Encoding: UTF8

Transmit

Within Options, under Transmit, mainly check the following settings:

• Send String Options: Check Terminate 'Send String' Data
  • Termination String: 0D 0A (appends CRLF at the end in the send screen)

Usage Examples

Interactive Mode

For interactive mode, it is recommended to set Options > Terminal > Terminal Mode to Raw Mode.

After clicking Connect, select the main screen and input the + character three times.

You can use interactive mode by directly typing characters just like in the TWELITE STAGE app.

Serial Communication App Format Mode (ASCII)

When handling sequences composed of ASCII strings starting with : and ending with CRLF, as in the serial communication app’s ASCII format mode, setting Options > Terminal > Terminal Mode to Line Mode is convenient.

You can input line by line using the Enter key, and press the ↑ cursor key to refer to the history.

The following figure shows an example of sending the byte sequence 0x11 0x22 0x33 0xAA 0xBB 0xCC several times from the Parent to all Children using the simplified format.

Serial Communication App Format Mode (Binary)

In the serial communication app’s binary format mode, set Options > Terminal > Terminal Mode to Raw Mode and uncheck Options > Transmit > Send String Options > Terminate 'Send String' Data.

To display received data in hexadecimal, select View > View Hex.

To send data represented in hexadecimal, select Connection > Send String... to open the send screen, and choose the Hex radio button.

The following figure shows an example of sending the byte sequence 0x11 0x22 0x33 0xAA 0xBB 0xCC from the Parent to all Children using the simplified format.

2 - Using Interactive Mode Programmatically

Mechanism of Interactive Mode

In its initial state, the RX port of TWELITE operates at 115200bps 8N1. To transition into interactive mode, input + three times at intervals of approximately 200 to 1000ms. Since interactive mode accepts only ASCII characters as input, once entered, it can be freely controlled programmatically.

Implementation Example

Reading Configuration Values Using Python

Below is a script that reads the serial ID and configuration values from a TWELITE device programmed with the serial communication app App_Uart, via TWELITE R2/R3.

pip install tweliter

Script

Using Python 3.12.

The get_serial_id_and_settings() function can be reused for user scripts.

# -*- coding: utf-8 -*-

import time
import re

from tweliter import Tweliter  # Mono Wireless module for TWELITE R devices


def get_serial_id_and_settings() -> tuple[str, dict[str, str]] | None:
    """
    Get the serial ID and settings from the interactive mode of a TWELITE R device.

    Returns:
        tuple[str, dict[str, str]] | None:
            A tuple containing:
            - str: the serial ID (e.g., "0x82010079")
            - dict[str, str]: the settings dictionary (e.g., {'a': '0x67720103', ...})
            Returns None if the device cannot be accessed or the output is invalid.

    Notes:
        Example output from the interactive mode of an App_Uart device:
        --- CONFIG/TWE UART APP V1-04-6/SID=0x82010079/LID=0x78 -- ---
         a: set Application ID (0x67720103)
         i: set Device ID (120=0x78)
         c: set Channels (18)
         x: set RF Conf (3)
         r: set Role (0x0)
         l: set Layer (0x1)
         b: set UART baud (38400)
         B: set UART option (8N1)
         m: set UART mode (E)
         k: set Tx Trigger (sep=0x0d0a, min_bytes=0 dly=0[ms])
         h: set header format [;U;%t;%i;0x%A;%q;%s;<*;%X;\n]
         C: set crypt mode (0)
         o: set option bits (0x00000100)
        ---
         S: save Configuration
         R: reset to Defaults
    """
    try:
        with Tweliter(
            type_filter=Tweliter.Type.TWELITE_R2 | Tweliter.Type.TWELITE_R3
        ) as liter:
            # Reset the device
            liter.reset_device()

            # Get the serial port instance (pyserial)
            ser = liter.get_serial_instance()
            ser.timeout = 1.0

            # Enter to the interactive mode
            for _ in range(3):
                ser.write("+")
                time.sleep(0.3)

            # Read the output
            raw_output = ser.read_until(b"S:").decode("utf-8")

            # Reset the device (Exit interactive mode)
            liter.reset_device()
    except IOError as e:
        print(f"Couldn't open the device {e}")
        return None

    # Find the settings block in the output
    filter_output = re.search(r"---(.*?)---(.*?)---", raw_output, re.DOTALL)
    if filter_output:
        information_line = filter_output.group(1)
        settings_block = filter_output.group(2)
    else:
        print("No settings block found.")
        return None

    # Extract serial id from the information line
    serial_id_match = re.search(r"SID=0x([0-9A-Fa-f]+)", information_line)
    if serial_id_match:
        serial_id = f"0x{serial_id_match.group(1)}"
    else:
        print("Serial ID not found.")
        return None

    # Extract key-value pairs (str,str) from the settings block
    settings_dict = dict(
        re.findall(r"^\s*(\w):.*?\(([^()]*)\)", settings_block, re.MULTILINE)
    )

    return serial_id, settings_dict


def main() -> None:
    # Get the serial ID and settings from the device
    result = get_serial_id_and_settings()
    if result is None:
        print("Failed to retrieve serial ID and settings.")
        return
    serial_id, settings = result

    # Show the results
    print(f"Serial ID: {serial_id}")
    for id, value in settings.items():
        match id:
            case "a":
                print(f"Application ID: {value}")
            # case "i":
            #     print(f"Logical ID: {value}")
            # case "c":
            #     print(f"Channel: {value}")


if __name__ == "__main__":
    main()

Explanation

Flow of Reading Output from Interactive Mode

1. Reset the TWELITE
   • Resetting brings the device back to its initial state for entering interactive mode. This reset is performed by controlling the reset pin on TWELITE R2/R3.
2. Obtain the serial port instance
   • Using pyserial, obtain an instance for accessing serial I/O of TWELITE from the PC. Through this instance, you can send commands and read data.
3. Input + three times
   • By sending + three times at fixed intervals (200–1000ms), TWELITE transitions into interactive mode. This method is the same as manual operation by the user.
4. Read output up to the line starting with S:
   • In interactive mode, the line S: appears after a series of configuration items. Reading up to this point ensures that all configuration contents are retrieved.
5. Reset the TWELITE
   • After reading, reset again to return from interactive mode to normal operation.

with Tweliter(
    type_filter=Tweliter.Type.TWELITE_R2 | Tweliter.Type.TWELITE_R3
) as liter:
    # Reset the device
    liter.reset_device()

    # Get the serial port instance (pyserial)
    ser = liter.get_serial_instance()
    ser.timeout = 1.0

    # Enter to the interactive mode
    for _ in range(3):
        ser.write("+")
        time.sleep(0.3)

    # Read the output
    raw_output = ser.read_until(b"S:").decode("utf-8")

    # Reset the device (Exit interactive mode)
    liter.reset_device()

Flow of Interpreting Output from Interactive Mode

1. Extract the line and the block enclosed by ---
   • Use re.search(r"---(.*?)---(.*?)---", raw_output, re.DOTALL) to retrieve the full configuration info from the interactive mode output, divided into two parts: information_line (containing serial ID etc.), and settings_block (listing configuration items). re.DOTALL enables matching across multiple lines.
2. Extract the serial ID from the first line
   • Use re.search(r"SID=0x([0-9A-Fa-f]+)", information_line) to obtain the hexadecimal ID following SID=0x, format it as a string like 0x82010079. Both uppercase and lowercase hex digits are matched.
3. Extract command ID and value pairs from the block
   • Use re.findall(r"^\s*(\w):.*?\(([^()]*)\)", settings_block, re.MULTILINE) to extract lines in the format like a: ... (value), retrieving the one-letter command ID and the value inside parentheses. Leading spaces and any characters after the colon are ignored. re.MULTILINE enables matching across multiple lines.

# Find the settings block in the output
filter_output = re.search(r"---(.*?)---(.*?)---", raw_output, re.DOTALL)
if filter_output:
    information_line = filter_output.group(1)
    settings_block = filter_output.group(2)
else:
    print("No settings block found.")
    return None

# Extract serial id from the information line
serial_id_match = re.search(r"SID=0x([0-9A-Fa-f]+)", information_line)
if serial_id_match:
    serial_id = f"0x{serial_id_match.group(1)}"
else:
    print("Serial ID not found.")
    return None

# Extract key-value pairs (str,str) from the settings block
settings_dict = dict(
    re.findall(r"^\s*(\w):.*?\(([^()]*)\)", settings_block, re.MULTILINE)
)

return serial_id, settings_dict