MWings is a library used on a terminal connected to a TWELITE programmed with the parent/repeater application (App_Wings). It interprets the formatted strings output by App_Wings and provides the data received by the parent device to the terminal. It also constructs commands to App_Wings to control child devices.

1 - TWELITE Wings API / MWings for 32-bit Arduinos

MWings for 32-bit Arduino boards

TWELITE Wings API for 32-bit Arduino boards.

The MWings library enables easy communication with all TWELITE series products such as TWELITE CUE / TWELITE ARIA, TWELITE PAL, TWELITE DIP, and TWELITE UART.

1.1 - TWELITE Wings API / MWings for 32-bit Arduinos

Latest Version

TWELITE Wings API for 32-bit Arduino boards.

The MWings library makes it easy to communicate with all TWELITE series products such as TWELITE CUE / TWELITE ARIA, TWELITE PAL, TWELITE DIP, and TWELITE UART.

GitHub: monowireless/mwings_arduino

1.1.1 - List of Data Types and Procedures

List of MWings-specific data types and procedures for 32-bit Arduino boards

This is a list of MWings-specific data types and procedures. Click here for a list of classes.

Structures

`BarePacket`

Stores raw data extracted from the packet received by the parent device from a child device.

MWings_Common.h

Data

Type	Name	Description
`uint8_t*`	`u8Payload`	Payload data converted to binary (excluding `:`, checksum, and `CRLF`)
`uint16_t`	`u16PayloadSize`	Byte size of the above data
`uint8_t`	`u8Checksum`	Checksum of the above data

Procedures

Type and Name	Description
`uint8_t* u8From(int)`	Gets payload data from the specified position onward
`uint8_t u8At(int)`	Gets the payload data at the specified position as an 8-bit unsigned integer
`int8_t i8At(int)`	Gets the payload data at the specified position as an 8-bit signed integer
`uint16_t u16At(int)`	Gets the payload data at the specified position as a 16-bit unsigned integer
`int16_t i16At(int)`	Gets the payload data at the specified position as a 16-bit signed integer
`uint32_t u32At(int)`	Gets the payload data at the specified position as a 32-bit unsigned integer
`int32_t i32At(int)`	Gets the payload data at the specified position as a 32-bit signed integer

`mwings::ParsedPacketBase`

Abstract structure that stores parsed data received by the parent device from a child device.

MWings_Common.h

Data

Type	Name	Description
`uint32_t`	`u32SourceSerialId`	Serial ID of the sender
`uint8_t`	`u8SourceLogicalId`	Logical device ID of the sender
`uint16_t`	`u16SequenceNumber`	Sequence number
`uint8_t`	`u8Lqi`	LQI
`uint16_t`	`u16SupplyVoltage`	Supply voltage (mV)

This abstract structure defines data that is commonly used.

Structures derived from this abstract type (e.g., ParsedAppTwelitePacket) can access the data defined here.

`ParsedAppTwelitePacket`

Derived from mwings::ParsedPacketBase

Structure that stores data received by the parent device from a child device running the “Super Easy! Standard App”.

AppTwelitePacketParser.h

Data

Type	Name	Description
`uint8_t`	`u8DestinationLogicalId`	Logical device ID of the recipient
`uint8_t`	`u8RelayCount`	Number of relays
`bool`	`bPeriodic`	`true` if the packet is a periodic transmission
`bool[4]`	`bDiChanged`	`true` if DI1–4 changed
`bool[4]`	`bDiState`	`true` if DI1–4 are in Low state
`uint16_t[4]`	`u16AiVoltage`	Input voltage of AI1–4 (mV)

Please also refer to the manual of the parent/relay app.

`ParsedAppIoPacket`

Derived from mwings::ParsedPacketBase

Structure that stores data received by the parent device from a child device running the Remote App.

AppIoPacketParser.h

Data

Type	Name	Description
`uint8_t`	`u8RelayCount`	Number of relays
`bool[12]`	`bDiState`	`true` if each DI is in Low state
`bool[12]`	`bDiValid`	`true` if each DI is valid
`bool[12]`	`bDiInterrupt`	`true` if each DI has changed by interrupt

Please also refer to the manual of the parent/relay app.

`ParsedAppAriaPacket`

Derived from mwings::ParsedPacketBase

Structure that stores data received by the parent device from a child device running the Aria App (TWELITE ARIA mode).

AppAriaPacketParser.h

Data

Type	Name	Description
`uint32_t`	`u32RouterSerialId`	Serial ID of the first relay device `0x80000000` if not relayed (v1.2.2+)
`int16_t`	`i16Temp100x`	Temperature ×100 (Celsius)
`uint16_t`	`u16Humid100x`	Relative humidity ×100 (%)
`uint8_t`	`u8MagnetState`	Magnet Event ID
`bool`	`bMagnetStateChanged`	`true` if magnet sensor state changed

Magnet Event ID

ID	Description
`0x00`	No magnet nearby
`0x01`	North pole is nearby
`0x02`	South pole is nearby

Please also refer to the manual of the parent/relay app.

`ParsedAppCuePacket`

Derived from mwings::ParsedPacketBase

Structure that stores data received by the parent device from a child device running the Cue App (TWELITE CUE mode).

AppCuePacketParser.h

Data

Type	Name	Description
`uint32_t`	`u32RouterSerialId`	Serial ID of the first relay device `0x80000000` if not relayed (v1.2.2+)
`int16_t[10]`	`i16SamplesX`	X-axis acceleration samples (mG)
`int16_t[10]`	`i16SamplesY`	Y-axis acceleration samples (mG)
`int16_t[10]`	`i16SamplesZ`	Z-axis acceleration samples (mG)
`uint8_t`	`u8SampleCount`	Number of samples
`bool`	`bHasAccelEvent`	`true` if there is an acceleration event
`uint8_t`	`u8AccelEvent`	Acceleration Event ID
`uint8_t`	`u8MagnetState`	Magnet Event ID
`bool`	`bMagnetStateChanged`	`true` if magnet sensor state changed

Acceleration Event ID

ID	Description
`0x01`~`0x06`	Dice
`0x08`	Shake
`0x10`	Move

Magnet Event ID

ID	Description
`0x00`	No magnet nearby
`0x01`	North pole is nearby
`0x02`	South pole is nearby

Please also refer to the manual of the parent/relay app.

`ParsedAppPalAmbPacket`

Derived from mwings::ParsedPacketBase

Structure that stores data received by the parent device from a child device running the Pal App (environment sensor Pal).

AppPalAmbPacketParser.h

Data

Type	Name	Description
`uint32_t`	`u32RouterSerialId`	Serial ID of the first relay device `0x80000000` if not relayed (v1.2.2+)
`uint16_t`	`u16Ai1Voltage`	AI1 input voltage (mV)
`int16_t`	`i16Temp100x`	Temperature ×100 (Celsius)
`uint16_t`	`u16Humid100x`	Relative humidity ×100 (%)
`uint32_t`	`u32Illuminance`	Illuminance (lux)

Please also refer to the manual of the parent/relay app.

`ParsedAppPalMotPacket`

Derived from mwings::ParsedPacketBase

Structure that stores data received by the parent device from a child device running the Pal App (motion sensor Pal).

AppPalMotPacketParser.h

Data

Type	Name	Description
`uint32_t`	`u32RouterSerialId`	Serial ID of the first relay device `0x80000000` if not relayed (v1.2.2+)
`uint16_t`	`u16Ai1Voltage`	AI1 input voltage (mV)
`int16_t[16]`	`i16SamplesX`	X-axis acceleration samples (mG)
`int16_t[16]`	`i16SamplesY`	Y-axis acceleration samples (mG)
`int16_t[16]`	`i16SamplesZ`	Z-axis acceleration samples (mG)
`uint8_t`	`u8SampleCount`	Number of samples
`uint16_t`	`u16SamplingFrequency`	Sampling frequency (Hz)

Please also refer to the manual of the parent/relay app.

`ParsedAppPalOpenClosePacket`

Derived from mwings::ParsedPacketBase

Structure that stores data received by the parent device from a child device running the Pal App (open/close sensor Pal).

AppPalOpenClosePacketParser.h

Data

Type	Name	Description
`uint32_t`	`u32RouterSerialId`	Serial ID of the first relay device `0x80000000` if not relayed (v1.2.2+)
`uint16_t`	`u16Ai1Voltage`	AI1 input voltage (mV)
`uint8_t`	`u8MagnetState`	Magnet Event ID
`bool`	`bMagnetStateChanged`	`true` if magnet sensor state changed

Magnet Event ID

ID	Description
`0x00`	No magnet nearby
`0x01`	North pole is nearby
`0x02`	South pole is nearby

Please also refer to the manual of the parent/relay app.

`ParsedAppUartAsciiPacket`

Derived from mwings::ParsedPacketBase

Structure that stores data received by the parent device from a child device running the serial communication app (A mode, simple format).

AppUartAsciiPacketParser.h

Data

Type	Name	Description
`uint8_t`	`u8CommandId`	Command type (response ID)
`uint8_t*`	`u8Data`	Data
`uint16_t`	`u16DataSize`	Data length

Please also refer to the manual of the parent/relay app.

`ParsedAppUartAsciiExtendedPacket`

Derived from mwings::ParsedPacketBase

Structure that stores data received by the parent device from a child device running the serial communication app (A mode, extended format).

AppUartAsciiExtendedPacketParser.h

Data

Type	Name	Description
`uint32_t`	`u32DestinationSerialId`	Destination serial ID
`uint8_t`	`u8CommandId`	Command type (response ID)
`uint8_t*`	`u8Data`	Data
`uint16_t`	`u16DataSize`	Data length

Please also refer to the manual of the parent/relay app.

`ParsedActPacket`

Derived from mwings::ParsedPacketBase

Structure that stores data received by the parent device from a child device running the act app.

ActPacketParser.h

Data

Type	Name	Description
`uint8_t`	`u8CommandId`	Command type (response ID)
`uint8_t*`	`u8Data`	Data
`uint16_t`	`u16DataSize`	Data length

Please also refer to the manual of the parent/relay app.

`mwings::CommandBase`

Abstract structure that stores command data sent from the parent device to a child device.

MWings_Common.h

Data

Type	Name	Description
`uint8_t`	`u8DestinationLogicalId`	Destination logical device ID

Procedures

Type and Name	Description
`bool isValid()`	Returns `true` if the data is valid (pure virtual function)

This abstract structure defines data and procedures that are commonly used.

Structures derived from this abstract type (e.g., AppTweliteCommand) can access the data and procedures defined here.

`AppTweliteCommand`

Derived from mwings::CommandBase

Structure that stores command data sent from the parent device to a child device running the “Super Easy! Standard App”.

AppTweliteCommandSerializer.h

Data

Type	Name	Description
`bool[4]`	`bDiToChange`	`true` to change the state of each DO1-4
`bool[4]`	`bDiState`	`true` to set each DO1-4 to Low state
`bool[4]`	`bPwmToChange`	`true` to change the state of each PWM1-4
`uint16_t[4]`	`u16PwmDuty`	Duty ratio of each PWM1-4 (0-1024)

Please also refer to the manual of the “Super Easy! Standard App”.

`AppIoCommand`

Derived from mwings::CommandBase

Structure that stores command data sent from the parent device to a child device running the Remote App.

AppIoCommandSerializer.h

Data

Type	Name	Description
`bool[12]`	`bDiToChange`	`true` to change the state of each O1-12
`bool[12]`	`bDiState`	`true` to set each O1-12 to Low state

`AppPalNoticeCommand`

Derived from mwings::CommandBase

Structure that stores command data sent from the parent device to a child device running the Pal App (Notifier Pal).

AppPalNoticeCommandSerializer.h

Data

Type	Name	Description
`AppPalNoticeColor`	`eColor`	Lighting color
`AppPalNoticeBlinkSpeed`	`eBlinkSpeed`	Blinking speed
`uint8_t`	`u8Brightness`	Brightness (0-15)
`uint16_t`	`u16DurationInSec`	Lighting duration (seconds)

Please also refer to the manual of the parent/relay app.

`AppPalNoticeDetailedCommand`

Derived from mwings::CommandBase

Structure that stores command data sent from the parent device to a child device running the Pal App (Notifier Pal) — detailed format.

AppPalNoticeDetailedCommandSerializer.h

Data

Type	Name	Description
`AppPalNoticeRGBWColor`	`sRGBWColor`	Lighting color (RGBW)
`uint8_t`	`u8BlinkDutyPercentage`	Lighting time ratio (%)
`float`	`fBlinkPeriodInSec`	Blinking period (seconds)
`uint16_t`	`u16DurationInSec`	Lighting duration (seconds)

Please also refer to the manual of the parent/relay app.

`AppPalNoticeEventCommand`

Derived from mwings::CommandBase

Structure that stores command data (detailed format) sent from the parent device to a child device running the Pal App (Notifier Pal).

AppPalNoticeEventCommandSerializer.h

Data

Type	Name	Description
`uint8_t`	`u8EventId`	Event ID (0x00-0x10)

Please also refer to the manual of the parent/relay app.

`AppUartAsciiCommand`

Derived from mwings::CommandBase

Structure that stores command data (simple format) sent from the parent device to a child device running the serial communication app (A mode).

AppUartAsciiCommand.h

Data

Type	Name	Description
`uint8_t`	`u8CommandId`	Command type (response ID)
`uint8_t*`	`u8Data`	Data
`uint16_t`	`u16DataSize`	Data length

Command data represented by AppUartAsciiCommand does not require serialization.

Call Twelite.send() directly as shown below:

Twelite.send(command.u8DestinationLogicalId, command.u8CommandId,
                 command.u8Data, command.u16DataSize);

Please also refer to the manual of the parent/relay app.

`AppPalNoticeRGBWColor`

Structure that defines the lighting color (RGBW) used in AppPalNoticeDetailedCommand.

AppPalNoticeDetailedCommandSerializer.h

Data

Type	Name	Description
`uint8_t`	`red`	R (0-15)
`uint8_t`	`green`	G (0-15)
`uint8_t`	`blue`	B (0-15)
`uint8_t`	`white`	W (0-15)

Procedures

Type and Name	Description
`bool isValid()`	Returns `true` if the data is valid
`uint16_t u16()`	Returns a 16-bit unsigned integer with RGBW packed in order from LSB, 4 bits each

Enumerations

`AppPalNoticeColor`

enum class based on uint8_t ?

Enumeration that defines the lighting color used in AppPalNoticeCommand.

AppPalNoticeCommandSerializer.h

Identifier	Value	Description
`AppPalNoticeColor::RED`	`0`	Red
`AppPalNoticeColor::GREEN`	`1`	Green
`AppPalNoticeColor::BLUE`	`2`	Blue
`AppPalNoticeColor::YELLOW`	`3`	Yellow
`AppPalNoticeColor::PURPLE`	`4`	Purple
`AppPalNoticeColor::LIGHT_BLUE`	`5`	Light blue
`AppPalNoticeColor::WHITE`	`6`	White
`AppPalNoticeColor::WARM_WHITE`	`7`	Warm white

`AppPalNoticeBlinkSpeed`

enum class based on uint8_t

Enumeration that defines the blinking speed used in AppPalNoticeCommand.

AppPalNoticeCommandSerializer.h

Identifier	Value	Description
`AppPalNoticeBlinkSpeed::ALWAYS_ON`	`0`	Always on
`AppPalNoticeBlinkSpeed::SLOW`	`1`	Slow blinking
`AppPalNoticeBlinkSpeed::MEDIUM`	`2`	Medium blinking
`AppPalNoticeBlinkSpeed::FAST`	`3`	Fast blinking

Other Data Types

Procedures

`GetAppTweliteSerializedCommandPayloadSize()`

constexpr function ?

Returns the payload size (in bytes) of the serialized fixed-length data for AppTweliteCommand.

AppTweliteCommandSerializer.h

Type and Name	Description
`int GetAppTweliteSerializedCommandPayloadSize()`	Returns the number of bytes

`GetAppAppPalNoticeSerializedCommandPayloadSize()`

constexpr function

Returns the payload size (in bytes) of the serialized fixed-length data for AppPalNoticeCommand.

AppPalNoticeCommandSerializer.h

Type and Name	Description
`int GetAppPalNoticeSerializedCommandPayloadSize()`	Returns the number of bytes

`GetAppAppPalNoticeDetailedSerializedCommandPayloadSize()`

constexpr function

Returns the payload size (in bytes) of the serialized fixed-length data for AppPalNoticeDetailedCommand.

AppPalNoticeDetailedCommandSerializer.h

Type and Name	Description
`int GetAppPalNoticeDetailedSerializedCommandPayloadSize()`	Returns the number of bytes

`GetAppAppPalNoticeEventSerializedCommandPayloadSize()`

constexpr function

Returns the payload size (in bytes) of the serialized fixed-length data for AppPalNoticeEventCommand.

AppPalNoticeEventCommandSerializer.h

Type and Name	Description
`int GetAppPalNoticeEventSerializedCommandPayloadSize()`	Returns the number of bytes

1.1.2 - Class List

List of MWings classes for 32-bit Arduino boards

This is a list of classes.

1.1.2.1 - mwings::MWings Class

The main MWings class for 32-bit Arduino boards

This is an explanation of the mwings::MWings class.

The Twelite object used in sketches is an instance of the mwings::MWings class.

Normally, you do not need to instantiate the mwings::MWings class in your sketch. Please use the automatically initialized Twelite object.

Constructor

`MWings()`

Constructor. Initializes internal variables.

MWings()

MWings.h

Arguments

None

Destructor

`~MWings()`

Destructor. Releases allocated buffers.

~MWings()

Public Member Functions

`begin()`

Initializes TWELITE and starts it with the specified settings.

    bool begin(HardwareSerial& serial,
                   const int indicatorPin = -1,
                   const int resetPin = -1,
                   const int programPin = -1,
                   const uint8_t channel = 18,
                   const uint32_t appId = 0x67720102,
                   const uint8_t retryCount = 2,
                   const uint8_t txPower = 3,
                   const int rxBufferSize = 1024,
                   const int timeout = 100,
                   const uint32_t encryptKey = 0,
                   HardwareSerial* debugSerial = nullptr);

MWings.cpp

Arguments

Type	Name	Description	Optional	Remarks
`HardwareSerial&`	`serial`	Port communicating with TWELITE
`int`	`indicatorPin`	Pin connected to status LED	🆗	Can be omitted with `-1`
`int`	`resetPin`	TWELITE’s RST pin	🆗	Can be omitted with `-1`
`int`	`programPin`	TWELITE’s PRG pin	🆗	Can be omitted with `-1`
`uint8_t`	`channel`	Frequency channel	🆗	Default is `18`
`uint32_t`	`appId`	Application ID	🆗	Default is `0x67720102`
`uint8_t`	`retryCount`	Number of retries	🆗	0-9
`uint8_t`	`txPower`	Transmission power	🆗	0-3
`int`	`rxBufferSize`	Size of packet reception buffer	🆗	Binary-based
`int`	`timeout`	Timeout for each packet	🆗	Until reception completion
`uint32_t`	`encryptKey`	Encryption key	🆗	Disabled if `0`, available from v1.2.3+
`HardwareSerial*`	`debugSerial`	Debug output port	🆗

Return Value

Type	Value	Description	Remarks
`bool`	`true`	Success
	`false`	Error

`end()`

Initializes all internal variables.

inline void end()

MWings.h

Arguments

None

Return Value

None

`update()`

Reads the serial receive buffer and parses the ModBus ASCII format data sent from the parent device.

void update();

MWings.h

Arguments

None

Return Value

None

`on()` <`BarePacket`>

Registers a handler to process data sent from all child devices.

inline void on(void (*callback)(const BarePacket& packet))

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`void (*)(BarePacket&)`	`callback`	Event handler

For details on BarePacket, see Data and Procedures.

Return Value

None

`on()` <`ParsedAppTwelitePacket`>

Super easy! Registers a handler to process data sent from standard app child devices.

inline void on(void (*callback)(const ParsedAppTwelitePacket& packet))

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`void (*)(ParsedAppTwelitePacket&)`	`callback`	Event handler

For details on ParsedAppTwelitePacket, see Data and Procedures.

Return Value

None

`on()` <`ParsedAppIoPacket`>

Registers a handler to process data sent from remote control app child devices.

inline void on(void (*callback)(const ParsedAppIoPacket& packet))

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`void (*)(ParsedAppIoPacket&)`	`callback`	Event handler

For details on ParsedAppIoPacket, see Data and Procedures.

Return Value

None

`on()` <`ParsedAppAriaPacket`>

Registers a handler to process data sent from ARIA app (TWELITE ARIA mode) child devices.

inline void on(void (*callback)(const ParsedAppAriaPacket& packet))

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`void (*)(ParsedAppAriaPacket&)`	`callback`	Event handler

For details on ParsedAppAriaPacket, see Data and Procedures.

Return Value

None

`on()` <`ParsedAppCuePacket`>

Registers a handler to process data sent from CUE app (TWELITE CUE mode) child devices.

inline void on(void (*callback)(const ParsedAppCuePacket& packet))

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`void (*)(ParsedAppCuePacket&)`	`callback`	Event handler

For details on ParsedAppCuePacket, see Data and Procedures.

Return Value

None

`on()` <`ParsedAppPalOpenClosePacket`>

Registers a handler to process data sent from PAL app (open/close sensor PAL) child devices.

inline void on(void (*callback)(const ParsedAppPalOpenClosePacket& packet))

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`void (*)(ParsedAppPalOpenClosePacket&)`	`callback`	Event handler

For details on ParsedAppPalOpenClosePacket, see Data and Procedures.

Return Value

None

`on()` <`ParsedAppPalAmbPacket`>

Registers a handler to process data sent from PAL app (environment sensor PAL) child devices.

inline void on(void (*callback)(const ParsedAppPalAmbPacket& packet))

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`void (*)(ParsedAppPalAmbPacket&)`	`callback`	Event handler

For details on ParsedAppPalAmbPacket, see Data and Procedures.

Return Value

None

`on()` <`ParsedAppPalMotPacket`>

Registers a handler to process data sent from PAL app (motion sensor PAL) child devices.

inline void on(void (*callback)(const ParsedAppPalMotPacket& packet))

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`void (*)(ParsedAppPalMotPacket&)`	`callback`	Event handler

For details on ParsedAppPalMotPacket, see Data and Procedures.

Return Value

None

`on()` <`ParsedAppUartAsciiPacket`>

Registers a handler to process data (simple format) sent from serial communication app (A mode) child devices.

inline void on(void (*callback)(const ParsedAppUartAsciiPacket& packet))

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`void (*)(ParsedAppUartAsciiPacket&)`	`callback`	Event handler

For details on ParsedAppUartAsciiPacket, see Data and Procedures.

Return Value

None

`on()` <`ParsedAppUartAsciiExtendedPacket`>

Registers a handler to process data (extended format) sent from serial communication app (A mode) child devices.

inline void on(void (*callback)(const ParsedAppUartAsciiExtendedPacket& packet))

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`void (*)(ParsedAppUartAsciiExtendedPacket&)`	`callback`	Event handler

For details on ParsedAppUartAsciiExtendedPacket, see Data and Procedures.

Return Value

None

`on()` <`ParsedActPacket`>

Registers a handler to process data sent from act child devices.

inline void on(void (*callback)(const ParsedActPacket& packet))

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`void (*)(ParsedActPacket&)`	`callback`	Event handler

For details on ParsedActPacket, see Data and Procedures.

Return Value

None

`send()` <`uint8_t*, int, uint8_t`>

Sends an arbitrary command (ModBus ASCII format) to the parent device.

inline bool send(const uint8_t* const payload,
                     const int payloadSize,
                     const uint8_t checksum)

MWings.h

Arguments

Type	Name	Description	Remarks
`uint8_t*`	`payload`	Payload	Between `:` and LRC
`int`	`payloadSize`	Payload size
`uint8_t`	`checksum`	Checksum	LRC of the payload

Return Value

Type	Value	Description	Remarks
`bool`	`true`	Success
	`false`	Error

`send()` <`uint8_t*, int`>

Sends an arbitrary command (ModBus ASCII format) to the parent device (checksum automatically added).

inline bool send(const uint8_t* const payload,
                     const int payloadSize)

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`uint8_t*`	`payload`	Payload		Between `:` and LRC
`int`	`payloadSize`	Payload size

Return Value

Type	Value	Description	Remarks
`bool`	`true`	Success
	`false`	Error

`send()` <`uint8_t, uint8_t, uint8_t* int, uint8_t`>

Sends an arbitrary command (ModBus ASCII format) to the parent device.

inline bool send(const uint8_t logicalId,
                     const uint8_t commandId,
                     const uint8_t* const payload,
                     const int payloadSize,
                     const uint8_t checksum)

MWings.h

Arguments

Type	Name	Description	Remarks
`uint8_t`	`logicalId`	Destination logical device ID
`uint8_t`	`commandId`	Command type
`uint8_t*`	`payload`	Payload	Between `:` and LRC
`int`	`payloadSize`	Payload size
`uint8_t`	`checksum`	Checksum	LRC of the payload

Return Value

Type	Value	Description	Remarks
`bool`	`true`	Success
	`false`	Error

`send()` <`uint8_t, uint8_t, uint8_t* int`>

Sends an arbitrary command (ModBus ASCII format) to the parent device (checksum automatically added).

inline bool send(const uint8_t logicalId,
                     const uint8_t commandId,
                     const uint8_t* const payload,
                     const int payloadSize)

MWings.h

Arguments

Type	Name	Description	Remarks
`uint8_t`	`logicalId`	Destination logical device ID
`uint8_t`	`commandId`	Command type
`uint8_t*`	`payload`	Payload	Between `:` and LRC
`int`	`payloadSize`	Payload size

Return Value

Type	Value	Description	Remarks
`bool`	`true`	Success
	`false`	Error

`send()` <`AppTweliteCommand`>

Super easy! Sends a command to operate standard app terminals to the parent device.

inline bool send(AppTweliteCommand& command)

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`AppTweliteCommand`	`command`	Command data

For details on AppTweliteCommand, see Data and Procedures.

Return Value

Type	Value	Description	Remarks
`bool`	`true`	Success
	`false`	Error

`send()` <`AppIoCommand`>

Sends a command to operate remote control app terminals to the parent device.

inline bool send(AppIoCommand& command)

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`AppIoCommand`	`command`	Command data

For details on AppIoCommand, see Data and Procedures.

Return Value

Type	Value	Description	Remarks
`bool`	`true`	Success
	`false`	Error

`send()` <`AppPalNoticeCommand`>

Sends a command to operate PAL app (notification PAL) terminals to the parent device.

inline bool send(AppPalNoticeCommand& command)

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`AppPalNoticeCommand`	`command`	Command data

For details on AppPalNoticeCommand, see Data and Procedures.

Return Value

Type	Value	Description	Remarks
`bool`	`true`	Success
	`false`	Error

`send()` <`AppPalNoticeDetailedCommand`>

Sends a command (detailed format) to operate PAL app (notification PAL) terminals to the parent device.

inline bool send(AppPalNoticeDetailedCommand& command)

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`AppPalNoticeDetailedCommand`	`command`	Command data

For details on AppPalNoticeDetailedCommand, see Data and Procedures.

Return Value

Type	Value	Description	Remarks
`bool`	`true`	Success
	`false`	Error

`send()` <`AppPalNoticeEventCommand`>

Sends a command (event) to operate PAL app (notification PAL) terminals to the parent device.

inline bool send(AppPalNoticeEventCommand& command)

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`AppPalNoticeEventCommand`	`command`	Command data

For details on AppPalNoticeEventCommand, see Data and Procedures.

Return Value

Type	Value	Description	Remarks
`bool`	`true`	Success
	`false`	Error

`send()` <`AppPalUartAsciiCommand`>

Sends a command (simple format) to operate serial communication app (A mode) terminals to the parent device.

inline bool send(AppPalUartAsciiCommand& command)

MWings.h

Arguments

Type	Name	Description	Optional	Remarks
`AppPalUartAsciiCommand`	`command`	Command data

For details on AppPalUartAsciiCommand, see Data and Procedures.

Return Value

Type	Value	Description	Remarks
`bool`	`true`	Success
	`false`	Error

2 - TWELITE Wings API / MWings for Python

MWings for Modern Python

This is the TWELITE Wings API for modern Python.

The MWings library makes it easy to communicate with all TWELITE series products, including TWELITE CUE, TWELITE ARIA, TWELITE PAL, TWELITE DIP, and TWELITE UART.

2.1 - TWELITE Wings API / MWings for Python

Latest Version

This is the TWELITE Wings API for modern Python.

The MWings library makes it easy to communicate with all TWELITE series products, including TWELITE CUE, TWELITE ARIA, TWELITE PAL, TWELITE DIP, and TWELITE UART.

GitHub: monowireless/mwings_python

2.1.1 - mwings module

mwings

This is a top-level module that is often used directly.

src/mwings/__init__.py

`Twelite`

Interface for TWELITE

Inherits: threading.Thread

`Twelite()`

Twelite(port=None, rx_buffer_size=1024, timeout=100, tz=None, debugging=False)

Constructor. If a serial port is specified, it will be opened.

Parameters

Name	Type	Description
`port`	`optional str`	Serial port name: disabled if `None`
`rx_buffer_size`	`int`	Size of the receive buffer in bytes
`timeout`	`int`	Timeout between receiving packets (ms)
`tz`	`optional tzinfo`	Timezone applied to received data: UTC if `None`
`debugging`	`bool`	Debug output: enabled if `True`

Exceptions

IOError Serial port does not exist or is busy

`close()`

v1.0.10+

close()

Closes the serial port if it is open.

Usually, opened serial ports are automatically closed without calling close().

If you wish to close it explicitly, use this function or a with statement.

Parameters

None

Return value

None

`add_listener()`

@overload
add_listener(event, handler)
add_listener(event, handler)

Registers a receive handler.

Parameters

Name	Type	Description
`event`	`common.PacketType`	Identifier for the receive event
`handler`	`Callable[[common.BarePacket], None]`	Handler for the receive event (raw data)
	`Callable[[common.SomeCallable], None]`	Handler for the receive event (parsed data)

Return value

None

`on()`

on(event)

Registers a receive handler (decorator version).

Parameters

Name	Type	Description
`event`	`common.PacketType`	Identifier for the receive event

Return value

Type	Value	Description
`Callable[[common.SomeCallable], common.SomeCallable]`	-	Decorated function

`remove_all_listeners()`

v1.0.9+

remove_all_listeners()

Removes all registered receive handlers.

Parameters

None

Return value

None

`parse()`

@overload
parse(character, use_lf=False)
parse(character, use_lf=False)
parse(character, use_lf=False)

Parses the given received data.

Parameters

Name	Type	Description
`character`	`str`	Received data character: string of length 1
	`bytes`	Received data character: bytes of length 1
	`int`	Received data character: ASCII code
`use_lf`	`bool`	Type of newline character: LF if `True`

Return value

Type	Value	Description
`optional common.PacketType`	`common.PacketType`	Parsed packet type
	`None`	No parsed packet

Exceptions

RuntimeError Serial port is specified
ValueError Invalid character data detected

`parse_line()`

parse_line(line, use_lf=True)

Parses received data expressed as a single line string.

Parameters

Name	Type	Description
`line`	`str`	Received data string: a single line
`use_lf`	`bool`	Type of newline character: LF if `True`

Return value

Type	Value	Description
`optional common.PacketType`	`common.PacketType`	Parsed packet type
	`None`	No parsed packet

Exceptions

RuntimeError Serial port is specified

`receive()`

receive()

Parses data received on the serial port. Waits until the interpretation of one packet is complete.

This is a function for verification purposes. It blocks processing until a parsable packet is received, so it is not very practical.

Parameters

None

Return value

Type	Value	Description
`common.PacketType`	-	Parsed packet type

Exceptions

RuntimeError Serial port is not specified

`run()`

run()

Runs a subthread that performs reception. Overrides threading.Thread.run().

Do not call this method directly. It is automatically called when using start().

Parameters

None

Return value

None

`send()`

@overload
send(data)
send(data)

Sends commands from the serial port.

Parameters

Name	Type	Description
`data`	`common.SomeCommand`	Various command data
	`common.BarePacket`	Raw command data

Return value

Type	Value	Description
`bool`	`True`	Success
	`False`	Failure

Exceptions

RuntimeError Serial port is not specified

`set_timezone()`

set_timezone(tz)

Sets the timezone applied to received data.

Parameters

Name	Type	Description
`tz`	`tzinfo`	Any timezone: `ZoneInfo`
	`None`	UTC

Return value

None

`start()`

start()

Starts a subthread that performs reception. Overrides threading.Thread.start().

Parameters

None

Return value

None

Exceptions

RuntimeError Serial port is not specified

`stop()`

stop()

Stops the subthread that performs reception. Waits until handler calls for remaining received data are finished. This may take several seconds.

Parameters

None

Return value

None

Exceptions

RuntimeError Serial port is not specified

`update()`

update()

Parses data received on the serial port. Processes all data in the receive buffer and then immediately returns.

Parameters

None

Return value

Type	Value	Description
`optional common.PacketType`	`common.PacketType`	Parsed packet type
	`None`	No parsed packet

Exceptions

RuntimeError Serial port is not specified

`timezone`

@property
update()

Return value

Type	Value	Description
`tzinfo`	-	Timezone applied to received data

2.1.1.1 - mwings.common Module

Stores data and procedures used throughout the library.

Contains data and procedures used throughout the library.

src/mwings/common.py

`AccelEvent`

Identifiers for accelerometer events

Inherits from: enum.IntEnum

DICE_1 Dice: 1
DICE_2 Dice: 2
DICE_3 Dice: 3
DICE_4 Dice: 4
DICE_5 Dice: 5
DICE_6 Dice: 6
SHAKE Shake
MOVE Move
NONE No event

`AppPalNoticeBlinkSpeed`

Identifiers for AppPal notification blink speed

Inherits from: enum.IntEnum

ALWAYS_ON Always on
SLOW Slow blinking
MEDIUM Moderate blinking
FAST Fast blinking

`AppPalNoticeColor`

Identifiers for AppPal notification colors

Inherits from: enum.IntEnum

RED Red
GREEN Green
BLUE Blue
YELLOW Yellow
PURPLE Purple
LIGHT_BLUE Light blue
WHITE White
WARM_WHITE Warm white

`AppPalNoticeRGBWColor`

Notification color expressed in RGBW format

Inherits from: pydantic.BaseModel

`AppPalNoticeRGBWColor()`

AppPalNoticeRGBWColor(*, red=0, green=0, blue=0, white=15)

Parameters

Name	Type	Description
`red`	`common.UInt8`	Red: `0`–`0xF`
`green`	`common.UInt8`	Green: `0`–`0xF`
`blue`	`common.UInt8`	Blue: `0`–`0xF`
`white`	`common.UInt8`	White: `0`–`0xF`

You may pass a dictionary using ** unpacking.

`u16()`

u16()

Returns a 16-bit RGBW representation.

Parameters

None

Returns

Type	Value	Description
`common.UInt16`	-	16-bit RGBW representation

`BarePacket`

Raw packet data

Inherits from: pydantic.BaseModel

`BarePacket()`

BarePacket(payload, checksum=None, logical_and_command_id=None)

Parameters

Name	Type	Description
`payload`	`bytes`	Binary payload data
`checksum`	`optional common.UInt8`	LRC8: Automatically calculated if None
`logical_and_command_id`	`optional tuple(common.UInt8, common.UInt8)`	Logical device ID and command ID

If the third argument is specified, the corresponding header in the payload is omitted.

`i16_at()`

i16_at(index)

Gets a signed 16-bit integer from the specified position.

Parameters

Name	Type	Description
`index`	`int`	Position in payload

Returns

Type	Value	Description
`common.Int16`	-	Numeric data

`i32_at()`

i32_at(index)

Gets a signed 32-bit integer from the specified position.

Parameters

Name	Type	Description
`index`	`int`	Position in payload

Returns

Type	Value	Description
`common.Int32`	-	Numeric data

`i8_at()`

i8_at(index)

Gets a signed 8-bit integer from the specified position.

Parameters

Name	Type	Description
`index`	`int`	Position in payload

Returns

Type	Value	Description
`common.Int8`	-	Numeric data

`u16_at()`

u16_at(index)

Gets an unsigned 16-bit integer from the specified position.

Parameters

Name	Type	Description
`index`	`int`	Position in payload

Returns

Type	Value	Description
`common.UInt16`	-	Numeric data

`u32_at()`

u32_at(index)

Gets an unsigned 32-bit integer from the specified position.

Parameters

Name	Type	Description
`index`	`int`	Position in payload

Returns

Type	Value	Description
`common.UInt32`	-	Numeric data

`u8_at()`

u8_at(index)

Gets an unsigned 8-bit integer from the specified position.

Parameters

Name	Type	Description
`index`	`int`	Position in payload

Returns

Type	Value	Description
`common.UInt8`	-	Numeric data

`u8_from()`

u8_from(index)

Gets a byte sequence starting from the specified index.

Parameters

Name	Type	Description
`index`	`int`	Starting index in payload

Returns

Type	Value	Description
`optional bytes`	`bytes`	Partial byte sequence
	`None`	Invalid index

`CommandBase`

Abstract base class for commands

Inherits from: ABC, pydantic.BaseModel

`CommandBase()`

CommandBase(*, destination_logical_id=120)

Parameters

Name	Type	Description
`destination_logical_id`	`common.UInt8`	Logical device ID of destination

You may pass a dictionary using ** unpacking.

`is_valid()`

is_valid()

Checks if the command data is valid.

Parameters

None

Returns

Type	Value	Description
`bool`	`True`	Valid
	`False`	Invalid

`CommandSerializerBase`

Static abstract base class for command serializers

Inherits from: ABC

`serialize()`

serialize(command)

Expands the given command into a raw byte sequence.

Parameters

Name	Type	Description
`command`	`common.SomeCommand`	A command data object

Returns

Type	Value	Description
`optional common.BarePacket`	`common.BarePacket`	Expanded packet data
	`None`	Invalid command

`CrossSectional[T]`

Tuple-like class for storing cross-sectional data at a specific time point

Inherits from: common.FixedTuple[T]

`CrossSectional[T]()`

CrossSectional[T](length, elements)

Parameters

Name	Type	Description
`T`	`common.T`	Element type
`length`	`int`	Number of elements
`elements`	`Iterable[T]`	Element values

Exceptions

ValueError if the number of elements is invalid

`DtypedDecimal`

Abstract base class for numeric types that retain pandas dtype attribute

`get_dtype()`

get_dtype()

Retrieves the corresponding pandas dtype identifier.

Parameters

None

Returns

Type	Value	Description
`str`	-	`dtype` identifier

`FixedList[T]`

A class representing a fixed-length list

Inherits from: MutableSequence[T]

`FixedList[T]()`

FixedList[T](length, initial_elements)

Parameters

Name	Type	Description
`T`	`common.T`	Type of elements
`length`	`int`	Number of elements
`initial_elements`	`Iterable[T]`	Initial elements

Exceptions

ValueError if the number of elements is invalid

`insert()`

insert(index, value)

Inserts an element at the specified index.

Parameters

Name	Type	Description
`index`	`int`	Index to insert
`value`	`common.T`	Element to insert

Returns

None

Exceptions

IndexError if the index is invalid

`FixedTuple[T]`

Class representing a fixed-length tuple

Inherits from: Sequence[T]

`FixedTuple[T]()`

FixedTuple[T](length, elements)

Parameters

Name	Type	Description
`T`	`common.T`	Type of elements
`length`	`int`	Number of elements
`elements`	`Iterable[T]`	Elements

Exceptions

ValueError if the number of elements is invalid

`Float32`

Class to store a 32-bit floating point value

Inherits from: float, common.DtypedDecimal

`Float32()`

Float32(value=None)

Parameters

Name	Type	Description
`value`	`optional float`	Initial value

Exceptions

ValueError if the value is out of range

`Float64`

Class to store a 64-bit floating point value

Inherits from: float, common.DtypedDecimal

`Float64()`

Float64(value=None)

Parameters

Name	Type	Description
`value`	`optional float`	Initial value

Exceptions

ValueError if the value is out of range

`Int16`

Class to store a 16-bit integer

Inherits from: int, common.DtypedDecimal

`Int16()`

Int16(value=None)

Parameters

Name	Type	Description
`value`	`optional int`	Initial value

Exceptions

ValueError if the value is out of range

`hex()`

hex()

Returns a hexadecimal string representation.

Python’s built-in hex() function does not accept int subclasses. This method provides a similar interface as float.hex().

Returns

Type	Value	Description
`str`	-	Hexadecimal string (lowercase)

`Int32`

Class to store a 32-bit integer

Inherits from: int, common.DtypedDecimal

`Int32()`

Int32(value=None)

Parameters

Name	Type	Description
`value`	`optional int`	Initial value

Exceptions

ValueError if the value is out of range

`hex()`

Same as in Int16

`Int8`

Class to store an 8-bit integer

Inherits from: int, common.DtypedDecimal

`Int8()`

Int8(value=None)

Parameters

Name	Type	Description
`value`	`optional int`	Initial value

Exceptions

ValueError if the value is out of range

`hex()`

Same as in Int16

`MagnetState`

Identifiers for magnet events

Inherits from: enum.IntEnum

NOT_DETECTED No magnet
N_POLE_IS_CLOSE N pole is close
S_POLE_IS_CLOSE S pole is close

`PacketParserBase`

Static abstract base class for packet parsers

Inherits from: ABC

`is_valid()`

is_valid(bare_packet)

Checks if the given bare packet is valid.

`parse()`

parse(bare_packet)

Parses the given bare packet.

`PacketType`

Identifiers for packet types

Inherits from: enum.StrEnum

(Keep enum entries as-is, only translated names if needed)

`SomeCallable`, `SomeCommand`, `SomeParsedPacket`, `T`, `Timezone`

Keep these type variable and constant definitions unchanged.

`TimeSeries[T]`

Tuple-like class for storing time-series data

Inherits from: common.FixedTuple[T]

`TimeSeries[T]()`

TimeSeries[T](length, elements)

Parameters

Name	Type	Description
`T`	`common.T`	Element type
`length`	`int`	Number of elements
`elements`	`Iterable[T]`	Element values

Exceptions

ValueError if the number of elements is invalid

`UInt16`, `UInt32`, `UInt8`

Same structure as Int16, Int32, Int8 respectively with class names and descriptions updated accordingly:

Class to store a 16/32/8-bit unsigned integer
hex() method same as above

2.1.1.2 - mwings.parsers Module

Parsers for interpreting packets and handling their data.

2.1.1.2.1 - mwings.parsers.app_twelite Module

Parsers for packets sent from the Standard App (App_TWELITE) and data structures to store their contents.

Parsers for packets sent from the Extremely simple! Standard App (App_Twelite) and data structures to handle the data.

src/mwings/parsers/app_twelite.py

`PacketParser`

A static class parser that interprets packets representing data sent from the Extremely simple! Standard App.

Inherits: common.PacketParserBase

Lists members inherited from the base class.

`is_valid()`

is_valid(bare_packet)

Checks whether the given raw packet is valid.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`bool`	`True`	Valid, parsable
	`False`	Invalid, not parsable

`parse()`

parse(bare_packet)

Parses the given raw packet.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`optional ParsedPacket`	`ParsedPacket` instance	Parsed data
	`None`	Parsing failed

`ParsedPacket`

A structure to store the result of parsing packets representing data sent from the Extremely simple! Standard App.

Inherits: common.ParsedPacketBase

Also lists members inherited from the base class.

`ParsedPacket()`

ParsedPacket(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None, destination_logical_id=120, relay_count=0, periodic=False, di_changed=<mwings.common.CrossSectional object>, di_state=<mwings.common.CrossSectional object>, ai_voltage=<mwings.common.CrossSectional object>)

Parameters

Name	Type	Description
`time_parsed`	`optional AwareDatetime`	Parsing timestamp
`packet_type`	`common.PacketType`	Packet type
`sequence_number`	`optional common.UInt16`	Sequence number
`source_serial_id`	`common.UInt32`	Source serial ID
`source_logical_id`	`common.UInt8`	Source logical device ID
`lqi`	`optional common.UInt8`	Radio communication quality
`supply_voltage`	`optional common.UInt16`	Supply voltage (mV)
`destination_logical_id`	`common.UInt8`	Destination logical device ID
`relay_count`	`common.UInt8`	Relay count
`periodic`	`bool`	Whether periodic transmission
`di_changed`	`common.CrossSectional[bool](4)`	Digital interface change presence
`di_state`	`common.CrossSectional[bool](4)`	Digital interface state
`ai_voltage`	`common.CrossSectional[common.UInt16](4)`	Analog interface voltages

You can also pass a dictionary unpacked with **.

In addition to the variables specified as constructor arguments, the following @computed_field are available.

Name	Type	Description
`mwings_implementation`	`str`	MWings implementation (only `"python"`)
`mwings_version`	`str`	MWings version (PEP440 format)
`hostname`	`str`	Host machine name
`system_type`	`str`	System type (e.g., `"Linux"`)

Applicable field_validator

source_logical_id: Automatically validates value range
- check_source_logical_id(lid)
time_parsed: Automatically validates that timezone is attached
- datetime_must_be_clear(dt)
ai_voltage: Automatically validates value range
- check_ai_voltage(aiv)
destination_logical_id: Automatically validates value range
- check_destination_logical_id(lid)

Applicable field_serializer

packet_type: Serializes enum name as is for JSON etc.
- serialize_packet_type(packet_type)
source_serial_id: Serializes as hexadecimal string for JSON etc.
- serialize_source_serial_id(source_serial_id)
time_parsed: Serializes as ISO 8601 string for JSON etc.
- serialize_time_parsed(dt)

`to_df()`

to_df(include=None, exclude=None, verbose=True)

Converts parsed data to a pandas DataFrame.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of columns (members) to include in the DataFrame
`exclude`	`optional set[str]`	Set of columns (members) to exclude from the DataFrame
`verbose`	`bool`	Whether to include system information (only when other args are `None`)

Returns

Type	Value	Description
`pd.DataFrame`	-	Converted DataFrame

Exceptions

EnvironmentError if pandas is not installed

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

Converts parsed data to a dictionary.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the dictionary
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the dictionary
`verbose`	`bool`	Whether to include system information (only when other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`sort_keys`	`bool`	Whether to sort keys

Setting spread splits common.CrossSectional[T] type data.

Returns

Type	Value	Description
`dict[str, Any]`	-	Converted dictionary

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

Converts parsed data to JSON format.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the JSON
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the JSON
`verbose`	`bool`	Whether to include system information (only when other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`indent`	`optional int`	Number of spaces for indentation (`None` for no newline)
`sort_keys`	`bool`	Whether to sort keys

Setting spread splits common.CrossSectional[T] type data.

Returns

Type	Value	Description
`str`	-	Converted JSON string

`model_*()`

In addition, you can use various methods of pydantic.BaseModel.

2.1.1.2.2 - mwings.parsers.app_io Module

Parsers for packets sent from the remote control app and data structures to store their contents.

src/mwings/parsers/app_io.py

`PacketParser`

Static class for a parser that interprets packets representing data sent from the remote control app.

Inherits from: common.PacketParserBase

Members inherited from the base class are listed.

`is_valid()`

is_valid(bare_packet)

Checks whether the given raw packet is valid.

Arguments

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`bool`	`True`	Valid, parsable
	`False`	Invalid, not parsable

`parse()`

parse(bare_packet)

Parses the given raw packet.

Arguments

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`optional ParsedPacket`	Data of type `ParsedPacket`	Parsed data
	`None`	Parsing failed

`ParsedPacket`

Data structure to store the result of interpreting packets representing data sent from the remote control app.

Inherits from: common.ParsedPacketBase

Members inherited from the base class are also listed.

`ParsedPacket()`

ParsedPacket(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None, relay_count=0, di_state=<mwings.common.CrossSectional object>, di_valid=<mwings.common.CrossSectional object>, di_interrupt=<mwings.common.CrossSectional object>)

Arguments

Properties inherited from the base class are also listed.

Name	Type	Description
`time_parsed`	`optional AwareDatetime`	Parsing timestamp
`packet_type`	`common.PacketType`	Packet type
`sequence_number`	`optional common.UInt16`	Sequence number
`source_serial_id`	`common.UInt32`	Source serial ID
`source_logical_id`	`common.UInt8`	Source logical device ID
`lqi`	`optional common.UInt8`	Radio communication quality
`supply_voltage`	`optional common.UInt16`	Always `None` because ADC is not used
`relay_count`	`common.UInt8`	Number of relays
`di_changed`	`common.CrossSectional[bool](12)`	Digital interface change status
`di_state`	`common.CrossSectional[bool](12)`	Digital interface state
`di_interrupt`	`common.CrossSectional[bool](12)`	Digital interface interrupt status

You can pass a dictionary unpacked with **.

In addition to the constructor arguments, the following @computed_field are available.

Name	Type	Description
`mwings_implementation`	`str`	MWings implementation (`"python"` only)
`mwings_version`	`str`	MWings version (PEP440 format)
`hostname`	`str`	Host machine name
`system_type`	`str`	System type (e.g., `"Linux"`)

Applicable field_validator

source_logical_id: Automatically validates the value range
- check_source_logical_id(lid)
time_parsed: Automatically validates that timezone is attached
- datetime_must_be_clear(dt)

Applicable field_serializer

packet_type: Serializes the enum name as is for JSON, etc.
- serialize_packet_type(packet_type)
source_serial_id: Serializes as a hexadecimal string for JSON, etc.
- serialize_source_serial_id(source_serial_id)
time_parsed: Serializes as ISO 8601 string for JSON, etc.
- serialize_time_parsed(dt)

`to_df()`

to_df(include=None, exclude=None, verbose=True)

Converts the parsed data to a pandas DataFrame.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of columns (members) to include in the DataFrame
`exclude`	`optional set[str]`	Set of columns (members) to exclude from the DataFrame
`verbose`	`bool`	Include system information (only when other args are `None`)

Returns

Type	Value	Description
`pd.DataFrame`	-	Converted DataFrame

Exceptions

EnvironmentError if pandas is not installed

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

Converts the parsed data to a dictionary.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the dictionary
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the dictionary
`verbose`	`bool`	Include system information (only when other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`sort_keys`	`bool`	Whether to sort keys

When spread is set, data of type common.CrossSectional[T] is split.

Returns

Type	Value	Description
`dict[str, Any]`	-	Converted dictionary

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

Converts the parsed data to JSON format.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the JSON
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the JSON
`verbose`	`bool`	Include system information (only when other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`indent`	`optional int`	Number of spaces for indentation (`None` for no newline)
`sort_keys`	`bool`	Whether to sort keys

When spread is set, data of type common.CrossSectional[T] is split.

Returns

Type	Value	Description
`str`	-	Converted JSON string

`model_*()`

In addition, you can use all methods of pydantic.BaseModel.

2.1.1.2.3 - mwings.parsers.app_aria Module

Parsers for packets sent from App Aria and data structures to store their contents.

src/mwings/parsers/app_aria.py

`PacketParser`

Static class parser that interprets packets representing data sent from the Aria app

Inherits: common.PacketParserBase

Members inherited from the base class are listed.

`is_valid()`

is_valid(bare_packet)

Checks whether the given raw packet is valid.

Arguments

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`bool`	`True`	Valid, parsable
	`False`	Invalid, not parsable

`parse()`

parse(bare_packet)

Parses the given raw packet.

Arguments

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`optional ParsedPacket`	Data of type `ParsedPacket`	Parsed data
	`None`	Parsing failed

`ParsedPacket`

Structure to store the result of interpreting packets representing data sent from the Aria app

Inherits: common.ParsedPacketBase

Members inherited from the base class are also listed.

`ParsedPacket()`

ParsedPacket(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None, temp_100x=0, humid_100x=0, magnet_state=MagnetState.NOT_DETECTED, magnet_state_changed=False)

Arguments

Including inherited properties.

Name	Type	Description
`time_parsed`	`optional AwareDatetime`	Parsing time
`packet_type`	`common.PacketType`	Packet type
`sequence_number`	`optional common.UInt16`	Sequence number
`source_serial_id`	`common.UInt32`	Source serial ID
`source_logical_id`	`common.UInt8`	Source logical device ID
`lqi`	`optional common.UInt8`	Radio communication quality
`supply_voltage`	`optional common.UInt16`	Supply voltage (mV)
`router_serial_id`	`common.UInt32`	Serial ID of the first relay device (`0x80000000` if none) `v1.0.13+`
`temp_100x`	`common.Int16`	Temperature multiplied by 100 (°C)
`humid_100x`	`common.UInt16`	Relative humidity multiplied by 100
`magnet_state`	`common.MagnetState`	Magnet state
`magnet_state_changed`	`bool`	Whether the magnet state has changed

You can also pass a dictionary unpacked with **.

In addition to the variables specified in the constructor arguments, the following @computed_field are available.

Name	Type	Description
`mwings_implementation`	`str`	MWings implementation (only `"python"`)
`mwings_version`	`str`	MWings version (in PEP440 format)
`hostname`	`str`	Host machine name
`system_type`	`str`	System type (e.g., `"Linux"`)

Applicable field_validator

source_logical_id: Automatically validates the value range
- check_source_logical_id(lid)
time_parsed: Automatically validates that a timezone is attached
- datetime_must_be_clear(dt)

Applicable field_serializer

packet_type: Serializes the enum name as-is for JSON etc.
- serialize_packet_type(packet_type)
source_serial_id: Serializes as a hexadecimal string for JSON etc.
- serialize_source_serial_id(source_serial_id)
time_parsed: Serializes as ISO 8601 string for JSON etc.
- serialize_time_parsed(dt)
magnet_state: Serializes the enum name as-is for JSON etc.
- serialize_magnet_state(magnet_state)

`to_df()`

to_df(include=None, exclude=None, verbose=True)

Converts the parsed data to a pandas DataFrame format.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of columns (members) to include in the DataFrame
`exclude`	`optional set[str]`	Set of columns (members) to exclude from the DataFrame
`verbose`	`bool`	Whether to include system information (only if other arguments are `None`)

Returns

Type	Value	Description
`pd.DataFrame`	-	Converted DataFrame

Exceptions

EnvironmentError if pandas is not installed

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

Converts the parsed data to a dictionary format.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the dictionary
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the dictionary
`verbose`	`bool`	Whether to include system information (only if other arguments are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`sort_keys`	`bool`	Whether to sort keys

Returns

Type	Value	Description
`dict[str, Any]`	-	Converted dictionary

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

Converts the parsed data to JSON format.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the JSON
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the JSON
`verbose`	`bool`	Whether to include system information (only if other arguments are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`indent`	`optional int`	Number of spaces for indentation (`None` for no line breaks)
`sort_keys`	`bool`	Whether to sort keys

Returns

Type	Value	Description
`str`	-	Converted JSON string

`model_*()`

In addition, you can use various methods of pydantic.BaseModel.

2.1.1.2.4 - mwings.parsers.app_cue Module

Parsers for packets sent from the TWELITE CUE mode and data structures to store their contents.

src/mwings/parsers/app_cue.py

`PacketParser`

Static class for parsing packets representing data sent from the Cue app (TWELITE CUE mode).

Inherits from: common.PacketParserBase

Members inherited from the base class are listed.

`is_valid()`

is_valid(bare_packet)

Checks whether the given bare packet is valid.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`bool`	`True`	Valid and parsable
	`False`	Invalid and unparsable

`parse()`

parse(bare_packet)

Parses the given bare packet.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`optional ParsedPacket`	`ParsedPacket` typed data	Parsed data
	`None`	Unparsable

`ParsedPacket`

Structure to store the result of parsing packets representing data sent from the Cue app (TWELITE CUE mode).

Inherits from: common.ParsedPacketBase

Members inherited from the base class are also listed.

`ParsedPacket()`

ParsedPacket(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None, sample_count=10, samples_x=<mwings.common.TimeSeries object>, samples_y=<mwings.common.TimeSeries object>, samples_z=<mwings.common.TimeSeries object>, has_accel_event=False, accel_event=AccelEvent.NONE, magnet_state=MagnetState.NOT_DETECTED, magnet_state_changed=False)

Parameters

Including properties inherited from the base class.

Name	Type	Description
`time_parsed`	`optional AwareDatetime`	Parsing timestamp
`packet_type`	`common.PacketType`	Packet type
`sequence_number`	`optional common.UInt16`	Sequence number
`source_serial_id`	`common.UInt32`	Source serial ID
`source_logical_id`	`common.UInt8`	Source logical device ID
`lqi`	`optional common.UInt8`	Radio communication quality
`supply_voltage`	`optional common.UInt16`	Supply voltage (mV)
`router_serial_id`	`common.UInt32`	Serial ID of the first relay device (no relay is `0x80000000`) `v1.0.13+`
`sample_count`	`common.UInt8`	Number of accelerometer samples per axis
`samples_x`	`common.TimeSeries[common.Int16]`	X-axis accelerometer samples
`samples_y`	`common.TimeSeries[common.Int16]`	Y-axis accelerometer samples
`samples_z`	`common.TimeSeries[common.Int16]`	Z-axis accelerometer samples
`has_accel_event`	`bool`	Presence of accelerometer event
`accel_event`	`common.AccelEvent`	Accelerometer event
`magnet_state`	`common.MagnetState`	Magnet state
`magnet_state_changed`	`bool`	Whether magnet state has changed

You can also pass a dictionary unpacked with **.

In addition to the variables specified as constructor arguments, the following @computed_field are also available.

Name	Type	Description
`mwings_implementation`	`str`	MWings implementation (only `"python"`)
`mwings_version`	`str`	MWings version (in PEP440 format)
`hostname`	`str`	Host machine name
`system_type`	`str`	System type (e.g., `"Linux"`)

Applicable field_validator

source_logical_id: Automatically validates the value range
- check_source_logical_id(lid)
time_parsed: Automatically validates that a timezone is attached
- datetime_must_be_clear(dt)

Applicable field_serializer

packet_type: Serializes the enum name as is in JSON etc.
- serialize_packet_type(packet_type)
source_serial_id: Serializes as a hexadecimal string in JSON etc.
- serialize_source_serial_id(source_serial_id)
time_parsed: Serializes as an ISO 8601 string in JSON etc.
- serialize_time_parsed(dt)
accel_event: Serializes the enum name as is in JSON etc.
- serialize_accel_event(accel_event)
magnet_state: Serializes the enum name as is in JSON etc.
- serialize_magnet_state(magnet_state)

`to_df()`

to_df(include=None, exclude=None, verbose=True)

Converts the parsed data to a pandas DataFrame.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of columns (members) to include in the DataFrame
`exclude`	`optional set[str]`	Set of columns (members) to exclude from the DataFrame
`verbose`	`bool`	Whether to include system information (only when other arguments are `None`)

Returns

Type	Value	Description
`pd.DataFrame`	-	Converted DataFrame

Exceptions

EnvironmentError if pandas is not installed

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

Converts the parsed data to a dictionary.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the dictionary
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the dictionary
`verbose`	`bool`	Whether to include system information (only when other arguments are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`sort_keys`	`bool`	Whether to sort keys

Even if spread is set, time-series data of type common.TimeSeries[T] will not be split.

Returns

Type	Value	Description
`dict[str, Any]`	-	Converted dictionary

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

Converts the parsed data to JSON format.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the JSON
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the JSON
`verbose`	`bool`	Whether to include system information (only when other arguments are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`indent`	`optional int`	Number of spaces for indentation (`None` for no newline)
`sort_keys`	`bool`	Whether to sort keys

Even if spread is set, time-series data of type common.TimeSeries[T] will not be split.

Returns

Type	Value	Description
`str`	-	Converted JSON string

`model_*()`

In addition, you can use each method of pydantic.BaseModel.

2.1.1.2.5 - mwings.parsers.app_cue_pal_event Module

Parsers for packets sent from TWELITE CUE in PAL event mode (Dice/Move mode) and data structures to store their contents.

src/mwings/parsers/app_cue_pal_event.py

`PacketParser`

Static class parser that interprets packets representing data sent from the CUE app (operation PAL mode: Dice/Move mode).

Inherits from: common.PacketParserBase

Members inherited from the base class are listed.

`is_valid()`

is_valid(bare_packet)

Checks whether the given raw packet is valid.

Arguments

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`bool`	`True`	Valid, parsable
	`False`	Invalid, not parsable

`parse()`

parse(bare_packet)

Parses the given raw packet.

Arguments

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`optional ParsedPacket`	Data of type `ParsedPacket`	Parsed data
	`None`	Parsing failed

`ParsedPacket`

Data structure to store the result of parsing packets representing data sent from the CUE app (operation PAL mode: Dice/Move mode).

Inherits from: common.ParsedPacketBase

Members inherited from the base class are also listed.

`ParsedPacket()`

ParsedPacket(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None, ai1_voltage=0, accel_event=AccelEvent.NONE)

Arguments

Includes inherited properties as well.

Name	Type	Description
`time_parsed`	`optional AwareDatetime`	Parsing timestamp
`packet_type`	`common.PacketType`	Packet type
`sequence_number`	`optional common.UInt16`	Sequence number
`source_serial_id`	`common.UInt32`	Source serial ID
`source_logical_id`	`common.UInt8`	Source logical device ID
`lqi`	`optional common.UInt8`	Radio communication quality
`supply_voltage`	`optional common.UInt16`	Supply voltage (mV)
`router_serial_id`	`common.UInt32`	Serial ID of the first relay device (no relay is `0x80000000`) `v1.0.13+`
`ai1_voltage`	`common.UInt16`	Voltage of `AI1` (mV)
`accel_event`	`common.AccelEvent`	Acceleration event

You can also pass a dictionary unpacked with **.

In addition to the variables specified as constructor arguments, the following @computed_field are available.

Name	Type	Description
`mwings_implementation`	`str`	MWings implementation (only `"python"`)
`mwings_version`	`str`	MWings version (PEP440 format)
`hostname`	`str`	Host machine name
`system_type`	`str`	System type (e.g., `"Linux"`)

Applicable field_validator

source_logical_id: Automatically validates the value range
- check_source_logical_id(lid)
time_parsed: Automatically validates that timezone is attached
- datetime_must_be_clear(dt)

Applicable field_serializer

packet_type: Serializes enum name as-is for JSON etc.
- serialize_packet_type(packet_type)
source_serial_id: Serializes as hexadecimal string for JSON etc.
- serialize_source_serial_id(source_serial_id)
time_parsed: Serializes as ISO 8601 string for JSON etc.
- serialize_time_parsed(dt)
accel_event: Serializes enum name as-is for JSON etc.
- serialize_accel_event(accel_event)

`to_df()`

to_df(include=None, exclude=None, verbose=True)

Converts the parsed data into a pandas DataFrame format.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of columns (members) to include in the DataFrame
`exclude`	`optional set[str]`	Set of columns (members) to exclude from the DataFrame
`verbose`	`bool`	Include system information (only if other arguments are `None`)

Returns

Type	Value	Description
`pd.DataFrame`	-	Converted DataFrame

Exceptions

EnvironmentError if pandas is not installed

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

Converts the parsed data into dictionary format.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the dictionary
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the dictionary
`verbose`	`bool`	Include system information (only if other arguments are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`sort_keys`	`bool`	Whether to sort keys

If spread is set, data of type common.CrossSectional[T] will be split. Time-series data of type common.TimeSeries[T] will not be split.

Returns

Type	Value	Description
`dict[str, Any]`	-	Converted dictionary

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

Converts the parsed data into JSON format.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the JSON
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the JSON
`verbose`	`bool`	Include system information (only if other arguments are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`indent`	`optional int`	Number of spaces for indentation (`None` means no line breaks)
`sort_keys`	`bool`	Whether to sort keys

If spread is set, data of type common.CrossSectional[T] will be split. Time-series data of type common.TimeSeries[T] will not be split.

Returns

Type	Value	Description
`str`	-	Converted JSON string

`model_*()`

In addition, you can use the various methods of pydantic.BaseModel.

2.1.1.2.6 - mwings.parsers.app_pal_openclose Module

Parsers for packets sent from PAL App (Open/Close PAL) and data structures to store their contents.

src/mwings/parsers/app_pal_openclose.py

`PacketParser`

Static class parser that interprets packets representing data sent from PAL App (Open/Close PAL).

Inherits from: common.PacketParserBase

The members inherited from the base class are listed.

`is_valid()`

is_valid(bare_packet)

Checks whether the given raw packet is valid.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`bool`	`True`	Valid, parsable
	`False`	Invalid, not parsable

`parse()`

parse(bare_packet)

Parses the given raw packet.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`optional ParsedPacket`	Data of type `ParsedPacket`	Parsed data
	`None`	Parsing failed

`ParsedPacket`

Structure to store the result of parsing packets representing data sent from PAL App (Open/Close PAL).

Inherits from: common.ParsedPacketBase

Members inherited from the base class are also listed.

`ParsedPacket()`

ParsedPacket(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None, ai1_voltage=0, magnet_state=MagnetState.NOT_DETECTED, magnet_state_changed=False)

Parameters

Properties inherited from the base class are also listed.

Name	Type	Description
`time_parsed`	`optional AwareDatetime`	Parsing time
`packet_type`	`common.PacketType`	Packet type
`sequence_number`	`optional common.UInt16`	Sequence number
`source_serial_id`	`common.UInt32`	Source serial ID
`source_logical_id`	`common.UInt8`	Source logical device ID
`lqi`	`optional common.UInt8`	Radio communication quality
`supply_voltage`	`optional common.UInt16`	Supply voltage (mV)
`router_serial_id`	`common.UInt32`	Serial ID of the first relay device (0x80000000 if none) `v1.0.13+`
`ai1_voltage`	`common.UInt16`	Voltage of `AI1` (mV)
`magnet_state`	`common.MagnetState`	Magnet state
`magnet_state_changed`	`bool`	Whether the magnet state has changed

You can also pass a dictionary unpacked with **.

In addition to the constructor arguments, the following @computed_field are available.

Name	Type	Description
`mwings_implementation`	`str`	MWings implementation (`"python"` only)
`mwings_version`	`str`	MWings version (PEP440 format)
`hostname`	`str`	Host machine name
`system_type`	`str`	System type (e.g., `"Linux"`)

Applicable field_validator

source_logical_id: Automatically validates the value range
- check_source_logical_id(lid)
time_parsed: Automatically validates that a timezone is attached
- datetime_must_be_clear(dt)

Applicable field_serializer

packet_type: Serializes enum name directly for JSON etc.
- serialize_packet_type(packet_type)
source_serial_id: Serializes as hexadecimal string for JSON etc.
- serialize_source_serial_id(source_serial_id)
time_parsed: Serializes as ISO 8601 string for JSON etc.
- serialize_time_parsed(dt)
magnet_state: Serializes enum name directly for JSON etc.
- serialize_magnet_state(magnet_state)

`to_df()`

to_df(include=None, exclude=None, verbose=True)

Converts the parsed data into a pandas DataFrame.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of columns (members) to include in DataFrame
`exclude`	`optional set[str]`	Set of columns (members) to exclude from DataFrame
`verbose`	`bool`	Whether to include system information (only when other args are `None`)

Returns

Type	Value	Description
`pd.DataFrame`	-	Converted DataFrame

Exceptions

EnvironmentError if pandas is not installed

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

Converts the parsed data into a dictionary.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the dictionary
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the dictionary
`verbose`	`bool`	Whether to include system information (only when other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`sort_keys`	`bool`	Whether to sort by keys

Returns

Type	Value	Description
`dict[str, Any]`	-	Converted dictionary

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

Converts the parsed data into JSON format.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in JSON
`exclude`	`optional set[str]`	Set of keys (members) to exclude from JSON
`verbose`	`bool`	Whether to include system information (only when other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`indent`	`optional int`	Number of spaces for indentation (`None` for no newline)
`sort_keys`	`bool`	Whether to sort by keys

Returns

Type	Value	Description
`str`	-	Converted JSON string

`model_*()`

In addition, you can use various methods from pydantic.BaseModel.

2.1.1.2.7 - mwings.parsers.app_pal_amb Module

Parsers for packets sent from PAL App (Environmental PAL) and data structures to store their contents.

src/mwings/parsers/app_pal_amb.py

`PacketParser`

A static class parser that interprets packets representing data sent from PAL App (Environmental PAL).

Inherits from: common.PacketParserBase

The members inherited from the base class are listed.

`is_valid()`

is_valid(bare_packet)

Checks whether the given raw packet is valid.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`bool`	`True`	Valid, parsable
	`False`	Invalid, unparsable

`parse()`

parse(bare_packet)

Parses the given raw packet.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`optional ParsedPacket`	`ParsedPacket` instance	Parsed data
	`None`	Unparsable

`ParsedPacket`

A structure to store the result of parsing packets representing data sent from PAL App (Environmental PAL).

Inherits from: common.ParsedPacketBase

Members inherited from the base class are also listed.

`ParsedPacket()`

ParsedPacket(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None, ai1_voltage=0, temp_100x=0, humid_100x=0, illuminance=0)

Parameters

Including properties inherited from the base class.

Name	Type	Description
`time_parsed`	`optional AwareDatetime`	Parsing timestamp
`packet_type`	`common.PacketType`	Packet type
`sequence_number`	`optional common.UInt16`	Sequence number
`source_serial_id`	`common.UInt32`	Source serial ID
`source_logical_id`	`common.UInt8`	Source logical device ID
`lqi`	`optional common.UInt8`	Radio communication quality
`supply_voltage`	`optional common.UInt16`	Supply voltage (mV)
`router_serial_id`	`common.UInt32`	Serial ID of first relay device (`0x80000000` if none) `v1.0.13+`
`ai1_voltage`	`common.UInt16`	Voltage of `AI1` (mV)
`temp_100x`	`common.Int16`	Temperature multiplied by 100 (°C)
`humid_100x`	`common.UInt16`	Relative humidity multiplied by 100
`illuminance`	`common.UInt32`	Illuminance (lx)

You can also pass a dictionary unpacked with **.

In addition to the constructor arguments, the following @computed_field are available.

Name	Type	Description
`mwings_implementation`	`str`	MWings implementation (`"python"` only)
`mwings_version`	`str`	MWings version (PEP440 format)
`hostname`	`str`	Host machine name
`system_type`	`str`	System type (e.g., `"Linux"`)

Applicable field_validator

source_logical_id: Automatically validates the range of values
- check_source_logical_id(lid)
time_parsed: Automatically validates that timezone info is attached
- datetime_must_be_clear(dt)

Applicable field_serializer

packet_type: Serializes the enum name as is to JSON etc.
- serialize_packet_type(packet_type)
source_serial_id: Serializes as a hexadecimal string to JSON etc.
- serialize_source_serial_id(source_serial_id)
time_parsed: Serializes as ISO 8601 string to JSON etc.
- serialize_time_parsed(dt)

`to_df()`

to_df(include=None, exclude=None, verbose=True)

Converts the parsed data into a pandas DataFrame.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of columns (members) to include in the DataFrame
`exclude`	`optional set[str]`	Set of columns (members) to exclude from the DataFrame
`verbose`	`bool`	Whether to include system information (only if other args are `None`)

Returns

Type	Description
`pd.DataFrame`	Converted DataFrame

Exceptions

EnvironmentError if pandas is not installed

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

Converts the parsed data into a dictionary.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the dictionary
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the dictionary
`verbose`	`bool`	Whether to include system information (only if other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`sort_keys`	`bool`	Whether to sort keys

Returns

Type	Description
`dict[str, Any]`	Converted dictionary

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

Converts the parsed data into a JSON string.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the JSON
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the JSON
`verbose`	`bool`	Whether to include system information (only if other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`indent`	`optional int`	Number of indentation spaces (`None` for no newlines)
`sort_keys`	`bool`	Whether to sort keys

Returns

Type	Description
`str`	Converted JSON string

`model_*()`

In addition, you can use various methods of pydantic.BaseModel.

2.1.1.2.8 - mwings.parsers.app_pal_mot Module

Parsers for packets sent from PAL App (Motion PAL) or CUE App in Motion PAL Mode (accelerometer measurement).

Parsers for packets sent from PAL App (Motion PAL) or CUE App in Motion PAL Mode (accelerometer measurement), and data structures to store the parsed information.

src/mwings/parsers/app_pal_mot.py

`PacketParser`

A static class parser that interprets packets representing data sent from PAL App (Motion PAL) or CUE App (Motion PAL Mode: accelerometer measurement).

Inherits: common.PacketParserBase

Members inherited from the base class are listed.

`is_valid()`

is_valid(bare_packet)

Checks whether the given bare packet is valid.

Arguments

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`bool`	`True`	Valid, parsable
	`False`	Invalid, not parsable

`parse()`

parse(bare_packet)

Parses the given bare packet.

Arguments

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`optional ParsedPacket`	`ParsedPacket` instance	Parsed data
	`None`	Parsing failed

`ParsedPacket`

A data structure to store the result of parsing packets sent from PAL App (Motion PAL) or CUE App (Motion PAL Mode: accelerometer measurement).

Inherits: common.ParsedPacketBase

Members inherited from the base class are also listed.

`ParsedPacket()`

ParsedPacket(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None, ai1_voltage=0, sample_count=16, samples_x=<mwings.common.TimeSeries object>, samples_y=<mwings.common.TimeSeries object>, samples_z=<mwings.common.TimeSeries object>, sampling_frequency=25)

Arguments

Including properties inherited from the base class.

Name	Type	Description
`time_parsed`	`optional AwareDatetime`	Parsing timestamp
`packet_type`	`common.PacketType`	Packet type
`sequence_number`	`optional common.UInt16`	Sequence number
`source_serial_id`	`common.UInt32`	Source serial ID
`source_logical_id`	`common.UInt8`	Source logical device ID
`lqi`	`optional common.UInt8`	Radio communication quality
`supply_voltage`	`optional common.UInt16`	Supply voltage (mV)
`router_serial_id`	`common.UInt32`	Serial ID of the first relay device (0x80000000 if none) `v1.0.13+`
`ai1_voltage`	`common.UInt16`	Voltage of `AI1` (mV)
`sample_count`	`common.UInt8`	Number of acceleration samples per axis
`samples_x`	`common.TimeSeries[common.Int16]`	Acceleration samples on X axis
`samples_y`	`common.TimeSeries[common.Int16]`	Acceleration samples on Y axis
`samples_z`	`common.TimeSeries[common.Int16]`	Acceleration samples on Z axis
`sampling_frequency`	`common.UInt16`	Acceleration sampling frequency

You can also pass a dictionary unpacked with **.

In addition to constructor arguments, the following @computed_field fields are available.

Name	Type	Description
`mwings_implementation`	`str`	MWings implementation (only `"python"`)
`mwings_version`	`str`	MWings version (in PEP440 format)
`hostname`	`str`	Host machine name
`system_type`	`str`	System type (e.g., `"Linux"`)

Applied field_validator

source_logical_id: Automatically validates the value range
- check_source_logical_id(lid)
time_parsed: Automatically validates that timezone is attached
- datetime_must_be_clear(dt)
sampling_frequency: Validates the value
- check_sampling_frequency(freq)

Applied field_serializer

packet_type: Serializes enum name as is for JSON etc.
- serialize_packet_type(packet_type)
source_serial_id: Serializes as hexadecimal string for JSON etc.
- serialize_source_serial_id(source_serial_id)
time_parsed: Serializes as ISO 8601 string for JSON etc.
- serialize_time_parsed(dt)

`to_df()`

to_df(include=None, exclude=None, verbose=True)

Converts the parsed data into a pandas DataFrame.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of columns (members) to include in the DataFrame
`exclude`	`optional set[str]`	Set of columns (members) to exclude from the DataFrame
`verbose`	`bool`	Whether to include system information (only effective if other arguments are `None`)

Returns

Type	Description
`pd.DataFrame`	Converted DataFrame

Exceptions

EnvironmentError if pandas is not installed

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

Converts the parsed data into a dictionary.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the dictionary
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the dictionary
`verbose`	`bool`	Whether to include system information (only effective if other arguments are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`sort_keys`	`bool`	Whether to sort keys

Even if spread is set, common.TimeSeries[T] time series data is not split.

Returns

Type	Description
`dict[str, Any]`	Converted dictionary

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

Converts the parsed data into JSON format.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the JSON
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the JSON
`verbose`	`bool`	Whether to include system information (only effective if other arguments are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`indent`	`optional int`	Number of spaces for indentation (`None` for no newlines)
`sort_keys`	`bool`	Whether to sort keys

Even if spread is set, common.TimeSeries[T] time series data is not split.

Returns

Type	Description
`str`	Converted JSON string

`model_*()`

In addition, you can use various methods of pydantic.BaseModel.

2.1.1.2.9 - mwings.parsers.app_uart_ascii Module

Parsers for packets sent from the serial communication app (format mode: simplified).

Parsers for packets sent from the serial communication app (format mode: simplified) and data structures to store their contents.

src/mwings/parsers/app_uart_ascii.py

`PacketParser`

Static class parser that interprets packets representing data sent from the serial communication app (format mode: simplified).

Inherits: common.PacketParserBase

Members inherited from the base class are listed.

`is_valid()`

is_valid(bare_packet)

Checks whether the given bare packet is valid.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`bool`	`True`	Valid, can be parsed
	`False`	Invalid, cannot be parsed

`parse()`

parse(bare_packet)

Parses the given bare packet.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`optional ParsedPacket`	An instance of `ParsedPacket`	Parsed data
	`None`	Cannot parse

`ParsedPacket`

Structure to hold the results of parsing packets representing data sent from the serial communication app (format mode: simplified).

Inherits: common.ParsedPacketBase

Members inherited from the base class are also listed.

`ParsedPacket()`

ParsedPacket(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None, command_id=0, data=b'')

Parameters

Including inherited properties.

Name	Type	Description
`time_parsed`	`optional AwareDatetime`	Parsing timestamp
`packet_type`	`common.PacketType`	Packet type
`sequence_number`	`optional common.UInt16`	Not obtainable, always `None`
`source_serial_id`	`common.UInt32`	Source serial ID
`source_logical_id`	`common.UInt8`	Source logical device ID
`lqi`	`optional common.UInt8`	Not obtainable, always `None`
`supply_voltage`	`optional common.UInt16`	Not obtainable, always `None`
`command_id`	`common.UInt8`	Command ID
`data`	`bytes`	Data

You can also pass a dictionary unpacked with **.

In addition to the constructor arguments, the following @computed_field are available:

Name	Type	Description
`mwings_implementation`	`str`	MWings implementation (`"python"` only)
`mwings_version`	`str`	MWings version (PEP440 format)
`hostname`	`str`	Host machine name
`system_type`	`str`	System type (e.g., `"Linux"`)
`data_base64`	`str`	Base64 representation of the data
`data_hexstr`	`str`	Hexadecimal string representation of the data

data is not included in JSON etc. Please use data_base64 or data_hexstr.

Applied field_validator

source_logical_id: Automatically validates the value range
- check_source_logical_id(lid)
time_parsed: Automatically validates that a timezone is attached
- datetime_must_be_clear(dt)
sampling_frequency: Validates the value
- check_sampling_frequency(freq)
data: Automatically validates length
- check_data(data)

Applied field_serializer

packet_type: Serializes enum name as is into JSON etc.
- serialize_packet_type(packet_type)
source_serial_id: Serializes as hex string into JSON etc.
- serialize_source_serial_id(source_serial_id)
time_parsed: Serializes as ISO 8601 string into JSON etc.
- serialize_time_parsed(dt)
``

`to_df()`

to_df(include=None, exclude=None, verbose=True)

Converts parsed data into a pandas DataFrame.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of columns (members) to include in the DataFrame
`exclude`	`optional set[str]`	Set of columns (members) to exclude from the DataFrame
`verbose`	`bool`	Whether to include system information (only if other args are `None`)

Returns

Type	Value	Description
`pd.DataFrame`	-	Converted DataFrame

Exceptions

EnvironmentError if pandas is not installed

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

Converts parsed data into a dictionary.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the dictionary
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the dictionary
`verbose`	`bool`	Whether to include system information (only if other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`sort_keys`	`bool`	Whether to sort keys

Returns

Type	Value	Description
`dict[str, Any]`	-	Converted dictionary

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

Converts parsed data into JSON format.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in JSON
`exclude`	`optional set[str]`	Set of keys (members) to exclude from JSON
`verbose`	`bool`	Whether to include system information (only if other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`indent`	`optional int`	Number of indentation spaces (`None` for no newlines)
`sort_keys`	`bool`	Whether to sort keys

Returns

Type	Value	Description
`str`	-	Converted JSON string

`model_*()`

In addition, you can use various methods of pydantic.BaseModel.

2.1.1.2.10 - mwings.parsers.app_uart_ascii_extended Module

Parsers for packets sent from the serial communication app (format mode: extended).

Parsers for packets sent from the serial communication app (format mode: extended) and data structures to store their contents.

src/mwings/parsers/app_uart_ascii_extended.py

`PacketParser`

Static class parser for interpreting packets representing data sent from the serial communication app (format mode: extended).

Inherits from: common.PacketParserBase

The members inherited from the base class are listed.

`is_valid()`

is_valid(bare_packet)

Checks whether the given bare packet is valid.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`bool`	`True`	Valid, parsable
	`False`	Invalid, not parsable

`parse()`

parse(bare_packet)

Parses the given bare packet.

Parameters

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`optional ParsedPacket`	Instance of `ParsedPacket`	Parsed data
	`None`	Parsing failed

`ParsedPacket`

Data structure to store the results of parsing packets representing data sent from the serial communication app (format mode: extended).

Inherits from: common.ParsedPacketBase

Members inherited from the base class are also listed.

`ParsedPacket()`

ParsedPacket(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None, destination_serial_id=120, command_id=0, data=b'')

Parameters

Including inherited properties.

Name	Type	Description
`time_parsed`	`optional AwareDatetime`	Parsing timestamp
`packet_type`	`common.PacketType`	Packet type
`sequence_number`	`optional common.UInt16`	Not available, always `None`
`source_serial_id`	`common.UInt32`	Sender’s serial ID
`source_logical_id`	`common.UInt8`	Sender’s logical device ID
`lqi`	`common.UInt8`	Radio signal quality
`supply_voltage`	`optional common.UInt16`	Not available, always `None`
`destination_serial_id`	`common.UInt32`	Receiver’s serial ID
`command_id`	`common.UInt8`	Command ID
`data`	`bytes`	Data

You can also pass a dictionary unpacked with **.

In addition to the constructor arguments, the following @computed_field are available.

Name	Type	Description
`mwings_implementation`	`str`	MWings implementation (`"python"` only)
`mwings_version`	`str`	MWings version (PEP440 format)
`hostname`	`str`	Host machine name
`system_type`	`str`	System type (e.g., `"Linux"`)
`data_base64`	`str`	Base64 representation of the data
`data_hexstr`	`str`	Hexadecimal string representation of the data

The data field is not included in JSON, etc. Please use data_base64 or data_hexstr.

Applicable field_validator

source_logical_id: Automatically validates the value range
- check_source_logical_id(lid)
time_parsed: Automatically validates that the timezone is attached
- datetime_must_be_clear(dt)
sampling_frequency: Validates the value
- check_sampling_frequency(freq)
data: Automatically validates the length
- check_data(data)

Applicable field_serializer

packet_type: Serializes the enum name as-is in JSON, etc.
- serialize_packet_type(packet_type)
source_serial_id: Serializes as a hexadecimal string in JSON, etc.
- serialize_source_serial_id(source_serial_id)
time_parsed: Serializes as ISO 8601 string in JSON, etc.
- serialize_time_parsed(dt)
``

`to_df()`

to_df(include=None, exclude=None, verbose=True)

Converts the parsed data into a pandas DataFrame.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of columns (members) to include in the DataFrame
`exclude`	`optional set[str]`	Set of columns (members) to exclude from the DataFrame
`verbose`	`bool`	Whether to include system information (only when other arguments are `None`)

Returns

Type	Description
`pd.DataFrame`	Converted DataFrame

Exceptions

EnvironmentError if pandas is not installed

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

Converts the parsed data into a dictionary.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the dictionary
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the dictionary
`verbose`	`bool`	Whether to include system information (only when other arguments are `None`)
`spread`	`bool`	Whether to split list-like data that is not time series
`sort_keys`	`bool`	Whether to sort keys

Returns

Type	Description
`dict[str, Any]`	Converted dictionary

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

Converts the parsed data into JSON format.

Parameters

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the JSON
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the JSON
`verbose`	`bool`	Whether to include system information (only when other arguments are `None`)
`spread`	`bool`	Whether to split list-like data that is not time series
`indent`	`optional int`	Number of spaces for indentation (`None` for no line breaks)
`sort_keys`	`bool`	Whether to sort keys

Returns

Type	Description
`str`	Converted JSON string

`model_*()`

In addition, you can use various methods of pydantic.BaseModel.

2.1.1.2.11 - mwings.parsers.act Module

Parsers for packets sent from act and data structures to store their contents.

src/mwings/parsers/act.py

`PacketParser`

Static class to parse packets sent from act

Inherits: common.PacketParserBase

Lists members inherited from the base class.

`is_valid()`

is_valid(bare_packet)

Checks whether the given bare packet is valid.

Arguments

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`bool`	`True`	Valid, parsable
	`False`	Invalid, not parsable

`parse()`

parse(bare_packet)

Parses the given bare packet.

Arguments

Name	Type	Description
`bare_packet`	`common.BarePacket`	Raw packet data

Returns

Type	Value	Description
`optional ParsedPacket`	`ParsedPacket` instance	Parsed data
	`None`	Parsing failed

`ParsedPacket`

Structure to store the result of parsing packets sent from act

Inherits: common.ParsedPacketBase

Also lists members inherited from the base class.

`ParsedPacket()`

ParsedPacket(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None, command_id=0, data=b'')

Arguments

Includes properties inherited from the base class.

Name	Type	Description
`time_parsed`	`optional AwareDatetime`	Parsing timestamp
`packet_type`	`common.PacketType`	Packet type
`sequence_number`	`optional common.UInt16`	Not available, always `None`
`source_serial_id`	`common.UInt32`	Source serial ID
`source_logical_id`	`common.UInt8`	Source logical device ID
`lqi`	`optional common.UInt8`	Radio communication quality
`supply_voltage`	`optional common.UInt16`	Not available, always `None`
`command_id`	`common.UInt8`	Command ID
`data`	`bytes`	Data

You can also pass a dictionary unpacked with **.

In addition to the constructor arguments, the following @computed_field are available:

Name	Type	Description
`mwings_implementation`	`str`	MWings implementation (only `"python"`)
`mwings_version`	`str`	MWings version (PEP440 format)
`hostname`	`str`	Host machine name
`system_type`	`str`	System type (e.g., `"Linux"`)
`data_base64`	`str`	Base64 representation of the data
`data_hexstr`	`str`	Hexadecimal representation of the data

data is not included in JSON or similar outputs. Use data_base64 or data_hexstr instead.

Applicable field_validator

source_logical_id: Automatically validates value range
- check_source_logical_id(lid)
time_parsed: Automatically validates that timezone is attached
- datetime_must_be_clear(dt)
sampling_frequency: Validates the value
- check_sampling_frequency(freq)

Applicable field_serializer

packet_type: Serializes enum name as is to JSON etc.
- serialize_packet_type(packet_type)
source_serial_id: Serializes as hexadecimal string to JSON etc.
- serialize_source_serial_id(source_serial_id)
time_parsed: Serializes as ISO 8601 string to JSON etc.
- serialize_time_parsed(dt)

`to_df()`

to_df(include=None, exclude=None, verbose=True)

Converts parsed data into a pandas DataFrame.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of columns (members) to include in the DataFrame
`exclude`	`optional set[str]`	Set of columns (members) to exclude from the DataFrame
`verbose`	`bool`	Whether to include system information (only effective if other args are `None`)

Returns

Type	Value	Description
`pd.DataFrame`	-	Converted DataFrame

Exceptions

EnvironmentError if pandas is not available

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

Converts parsed data into a dictionary.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the dictionary
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the dictionary
`verbose`	`bool`	Whether to include system information (only effective if other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`sort_keys`	`bool`	Whether to sort keys

Returns

Type	Value	Description
`dict[str, Any]`	-	Converted dictionary

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

Converts parsed data into JSON format.

Arguments

Name	Type	Description
`include`	`optional set[str]`	Set of keys (members) to include in the JSON
`exclude`	`optional set[str]`	Set of keys (members) to exclude from the JSON
`verbose`	`bool`	Whether to include system information (only effective if other args are `None`)
`spread`	`bool`	Whether to split non-time-series list-like data
`indent`	`optional int`	Number of indent spaces (`None` for no line breaks)
`sort_keys`	`bool`	Whether to sort keys

Returns

Type	Value	Description
`str`	-	Converted JSON string

`model_*()`

In addition, you can use various methods of pydantic.BaseModel.

2.1.1.3 - mwings.serializers Module

Serializers to generate commands and data structures to handle them.

2.1.1.3.1 - mwings.serializers.app_twelite Module

mwings.serializers.app_twelite

Serializers to generate commands representing packets for the Extremely Simple! Standard App, and data structures to handle them.

src/mwings/serializers/app_twelite.py

`CommandSerializer`

Static class to generate commands representing packets for the Extremely Simple! Standard App

Inherits: common.CommandSerializerBase

Members inherited from the base class are listed.

`serialize()`

serialize(command)

Expands the given command into a raw byte sequence.

Arguments

Name	Type	Description
`command`	`Command`	Command data

Returns

Type	Value	Description
`optional common.BarePacket`	`common.BarePacket`	Expanded data
	`None`	Invalid command data

`Command`

Structure to store data used to generate commands representing packets for the Extremely Simple! Standard App

Inherits: common.CommandBase

Members inherited from the base class are also listed.

`Command()`

Command(*, destination_logical_id=120, di_to_change=<mwings.common.FixedList object>, di_state=<mwings.common.FixedList object>, pwm_to_change=<mwings.common.FixedList object>, pwm_duty=<mwings.common.FixedList object>)

Arguments

Name	Type	Description
`destination_logical_id`	`common.UInt8`	Destination logical device ID
`di_to_change`	`common.FixedList[bool](4)`	Digital interfaces to change
`di_state`	`common.FixedList[bool](4)`	Digital interface states after change
`pwm_to_change`	`common.FixedList[bool](4)`	PWM interfaces to change
`pwm_duty`	`common.FixedList[int](4)`	PWM interface duty after change

You can also pass a dictionary unpacked with **.

Values for pwm_duty should be between 0 and 1024. A value of 0xFFFF indicates invalid.

`is_valid()`

is_valid()

Checks whether the command data is valid.

Arguments

None

Returns

Type	Value	Description
`bool`	`True`	Valid
	`False`	Invalid

`model_*()`

In addition, you can use various methods from pydantic.BaseModel.

2.1.1.3.2 - mwings.serializers.app_io Module

mwings.serializers.app_io

Serializers that generate commands representing packets to be sent to the remote control app, and the data structures to handle them.

src/mwings/serializers/app_io.py

`CommandSerializer`

Static class that serializes commands representing packets to be sent to the remote control app

Inherits from: common.CommandSerializerBase

Members inherited from the base class are listed.

`serialize()`

serialize(command)

Expands the given command into a raw packet byte sequence.

Parameters

Name	Type	Description
`command`	`Command`	Command data

Returns

Type	Value	Description
`optional common.BarePacket`	`common.BarePacket`	Expanded data
	`None`	Invalid command data

`Command`

Data structure to hold data used to generate commands representing packets to be sent to the remote control app

Inherits from: common.CommandBase

Members inherited from the base class are also listed.

`Command()`

Command(*, destination_logical_id=120, di_to_change=<mwings.common.FixedList object>, di_state=<mwings.common.FixedList object>)

Parameters

Name	Type	Description
`destination_logical_id`	`common.UInt8`	Destination logical device ID
`di_to_change`	`common.FixedList[bool](12)`	Digital interfaces to change
`di_state`	`common.FixedList[bool](12)`	State of digital interfaces after change

You can also pass a dictionary unpacked with **.

`is_valid()`

is_valid()

Checks whether the command data is valid.

Parameters

None

Returns

Type	Value	Description
`bool`	`True`	Valid
	`False`	Invalid

`model_*()`

In addition, you can use various methods from pydantic.BaseModel.

2.1.1.3.3 - mwings.serializers.app_pal_notice Module

mwings.serializers.app_pal_notice

Serializers that generate commands representing packets to be sent to the PAL App (Notification PAL), and the data structures to handle them.

src/mwings/serializers/app_pal_notice.py

`CommandSerializer`

A static class serializer that generates commands representing packets to be sent to the PAL App (Notification PAL).

Inherits: common.CommandSerializerBase

The members inherited from the base class are listed.

`serialize()`

serialize(command)

Expands the given command into a raw packet byte sequence.

Arguments

Name	Type	Description
`command`	`Command`	Command data

Returns

Type	Value	Description
`optional common.BarePacket`	`common.BarePacket`	Expanded data
	`None`	Invalid command data

`Command`

A structure to store parameters used when generating commands representing packets to be sent to the PAL App (Notification PAL).

Inherits: common.CommandBase

Members inherited from the base class are also included.

`Command()`

Command(*, destination_logical_id=120, color=AppPalNoticeColor.WHITE, blink_speed=AppPalNoticeBlinkSpeed.ALWAYS_ON, brightness=8, duration_in_sec=5)

Arguments

Name	Type	Description
`destination_logical_id`	`common.UInt8`	Destination logical device ID
`color`	`common.AppPalNoticeColor`	Lighting color name
`blink_speed`	`common.AppPalNoticeBlinkSpeed`	Blinking speed
`brightness`	`common.UInt8`	Brightness
`duration_in_sec`	`common.UInt8`	Total lighting (blinking) duration in seconds

You can pass a dictionary unpacked with **.

`is_valid()`

is_valid()

Checks whether the command data is valid.

Arguments

None

Returns

Type	Value	Description
`bool`	`True`	Valid
	`False`	Invalid

`model_*()`

In addition to the above, you can use various methods of pydantic.BaseModel.

2.1.1.3.4 - mwings.serializers.app_pal_notice_detailed Module

mwings.serializers.app_pal_notice_detailed

Serializers that generate commands representing detailed packets to be sent to the PAL App (Notification PAL), and the data structures to handle them.

src/mwings/serializers/app_pal_notice_detailed.py

`CommandSerializer`

Static class serializer that generates commands representing detailed packets to be sent to the PAL App (Notification PAL).

Inherits from: common.CommandSerializerBase

Members inherited from the base class are listed.

`serialize()`

serialize(command)

Expands the given command into a raw packet byte sequence.

Parameters

Name	Type	Description
`command`	`Command`	Command data

Returns

Type	Value	Description
`optional common.BarePacket`	`common.BarePacket`	Expanded data
	`None`	Invalid command data

`Command`

Data structure for storing data used to generate commands representing detailed packets to be sent to the PAL App (Notification PAL).

Inherits from: common.CommandBase

Members inherited from the base class are also listed.

`Command()`

Command(*, destination_logical_id=120, color=AppPalNoticeRGBWColor(red=0, green=0, blue=0, white=15), blink_duty_percentage=100, blink_period_in_sec=1.0, duration_in_sec=1)

Parameters

Name	Type	Description
`destination_logical_id`	`common.UInt8`	Destination logical device ID
`color`	`common.AppPalNoticeRGBWColor`	RGBW color for illumination
`blink_duty_percentage`	`common.UInt8`	Percentage of on-time during blinking
`blink_period_in_sec`	`common.Float64`	Blink period in seconds
`duration_in_sec`	`common.UInt8`	Total duration of illumination (blinking)

You can also pass a dictionary unpacked with **.

`is_valid()`

is_valid()

Checks whether the command data is valid.

Parameters

None

Returns

Type	Value	Description
`bool`	`True`	Valid
	`False`	Invalid

`model_*()`

In addition, you can use various methods of pydantic.BaseModel.

2.1.1.3.5 - mwings.serializers.app_pal_notice_event Module

mwings.serializers.app_pal_notice_event

Serializers that generate commands representing event packets to be sent to the PAL App (Notification PAL), and the data structures to handle them.

src/mwings/serializers/app_pal_notice_event.py

`CommandSerializer`

Static class serializer that generates commands representing event data packets sent to the PAL App (Notification PAL)

Inherits from: common.CommandSerializerBase

The members inherited from the base class are listed.

`serialize()`

serialize(command)

Expands the given command into a raw packet byte sequence.

Arguments

Name	Type	Description
`command`	`Command`	Command data

Returns

Type	Value	Description
`optional common.BarePacket`	`common.BarePacket`	Expanded data
	`None`	Invalid command data

`Command`

Structure to hold data used when generating commands representing event data packets sent to the PAL App (Notification PAL)

Inherits from: common.CommandBase

Members inherited from the base class are also listed.

`Command()`

Command(*, destination_logical_id=120, event_id=0)

Arguments

Name	Type	Description
`destination_logical_id`	`common.UInt8`	Destination logical device ID
`event_id`	`common.UInt8`	Event ID

You can also pass a dictionary unpacked with **.

`is_valid()`

is_valid()

Checks whether the command data is valid.

Arguments

None

Returns

Type	Value	Description
`bool`	`True`	Valid
	`False`	Invalid

`model_*()`

In addition, you can use various methods of pydantic.BaseModel.

2.1.1.3.6 - mwings.serializers.app_uart_ascii Module

mwings.serializers.app_uart_ascii

Serializers that generate commands representing packets to be sent to the serial communication app (format mode: simplified), and the data structures to handle them.

src/mwings/serializers/app_uart_ascii.py

`CommandSerializer`

Static class serializer that generates commands representing packets to be sent to the serial communication app (format mode: simplified)

Inherits from: common.CommandSerializerBase

Members inherited from the base class are listed.

`serialize()`

serialize(command)

Expands the given command into a raw packet byte sequence.

Arguments

Name	Type	Description
`command`	`Command`	Command data

Returns

Type	Value	Description
`optional common.BarePacket`	`common.BarePacket`	Expanded data
	`None`	Invalid command data

`Command`

Structure to store data used to generate commands representing packets to be sent to the serial communication app (format mode: simplified)

Inherits from: common.CommandBase

Members inherited from the base class are also listed.

`Command()`

Command(*, destination_logical_id=120, command_id=0, data)

Arguments

Name	Type	Description
`destination_logical_id`	`common.UInt8`	Destination logical device ID
`command_id`	`common.UInt8`	Command ID
`data`	`bytes`	Data

You can pass a dictionary unpacked with **.

`is_valid()`

is_valid()

Checks whether the command data is valid.

Arguments

None

Returns

Type	Value	Description
`bool`	`True`	Valid
	`False`	Invalid

`model_*()`

In addition, you can use various methods from pydantic.BaseModel.

2.1.1.4 - mwings.utils Module

mwings.utils

Contains general-purpose utility functions.

src/mwings/utils.py

`ask_user()`

ask_user(prompt, regex, on_error, ex_verifier=None, max_attempts=None)

Gets input from the user via the console.

Arguments

Name	Type	Description
`prompt`	`str`	Message displayed in the prompt
`regex`	`str`	Regular expression to validate user input
`on_error`	`str`	Message displayed when user input is invalid
`ex_verifier`	`optional Callable[[str], bool]`	Function to further validate input string beyond regex
`max_attempts`	`optional int`	Number of retry attempts. `None` means unlimited

Returns

Type	Value	Description
`str`	-	Validated user input string

`ask_user_for_port()`

ask_user_for_port()

Prompts the user to select a port to use.

Arguments

None

Returns

Type	Value	Description
`str`	-	Selected port name

`byte_count_from()`

byte_count_from(character_count)

Converts the length of a byte sequence represented as an ASCII string to the length of its binary representation.

Arguments

Name	Type	Description
`character_count`	`int`	Length of the ASCII representation of the byte sequence

Returns

Type	Value	Description
`int`	-	Length of the byte sequence in binary form

`character_from()`

character_from(hexvalue)

Converts a number from 0x0 to 0xF to its hexadecimal character representation.

Arguments

Name	Type	Description
`hexvalue`	`int`	Number

Returns

Type	Value	Description
`int`	-	ASCII code of character

`find_ascii()`

find_ascii(port, data, timeout, debugging=False)

Waits to receive the specified ASCII string.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port
`data`	`str`	ASCII string
`timeout`	`int`	Timeout (seconds)
`debugging`	`bool`	Debug output

Returns

Type	Value	Description
`bool`	`True`	Reception confirmed
`bool`	`False`	Reception not confirmed

`find_binary()`

find_binary(port, data, timeout, debugging=False)

Waits to receive the specified byte sequence.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port
`data`	`str`	Byte sequence
`with_terminal`	`bool`	Whether to use terminal data
`terminal`	`int`	Data to treat as terminal
`timeout`	`int`	Timeout (seconds)
`debugging`	`bool`	Debug output

Returns

Type	Value	Description
`bool`	`True`	Reception confirmed
`bool`	`False`	Reception not confirmed

`flush_rx_buffer()`

flush_rx_buffer(port)

Clears the receive buffer.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port

Returns

None

`flush_tx_buffer()`

flush_tx_buffer(port)

Clears the transmit buffer.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port

Returns

None

`get_ports()`

get_ports()

Retrieves a list of available serial ports.

Arguments

None

Returns

Type	Value	Description
`list[str]`	-	List of port names

`hex_from()`

hex_from(character)

Converts an ASCII character representing a hexadecimal digit to its numeric value. The result is undefined for characters other than 0-9 and A-F.

Arguments

Name	Type	Description
`character`	`int`	ASCII code of the character

Returns

Type	Value	Description
`int`	-	Numeric value

`is_initialized()`

is_initialized(port)

Checks whether the serial port is initialized.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port

Returns

Type	Value	Description
`bool`	`True`	Initialized
	`False`	Not initialized

`is_readable()`

is_readable(port)

Checks whether data can be read from the serial port.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port

Returns

Type	Value	Description
`bool`	`True`	Data available in receive buffer
	`False`	Not readable

`is_there_some_ports()`

is_there_some_ports()

Checks whether any serial ports are available.

Arguments

None

Returns

Type	Value	Description
`bool`	`True`	Serial ports exist
	`False`	None available

`is_writable()`

is_writable(port)

Checks whether data can be written to the serial port.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port

Returns

Type	Value	Description
`bool`	`True`	Writable
	`False`	Not writable

`lrc8()`

lrc8(data)

Calculates the 8-bit LRC.

Arguments

Name	Type	Description
`data`	`bytes`	Byte sequence to calculate

Returns

Type	Value	Description
`int`	-	LRC8 value

`millis()`

millis()

Gets the current system time in milliseconds.

Arguments

None

Returns

Type	Value	Description
`int`	-	System time (ms)

`open_on_system()`

open_on_system(path)

Opens the specified file path with the system’s default application.

Arguments

Name	Type	Description
`path`	`Path`	File path

Returns

None

`write_binary()`

write_binary(port, data)

Sends a byte sequence to the serial port.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port
`data`	`int`	Data to send
	`bytes`	Sequence of data to send

Returns

None

`write_in_ascii()`

write_in_ascii(port, data)

Sends an ASCII representation of a byte sequence to the serial port.

Arguments

Name	Type	Description
`port`	`serial.Serial`	Serial port
`data`	`int`	Character to send
	`bytes`	String to send

Returns

None

TWELITE Wings API / MWings

1 - TWELITE Wings API / MWings for 32-bit Arduinos

1.1 - TWELITE Wings API / MWings for 32-bit Arduinos

1.1.1 - List of Data Types and Procedures

Structures

BarePacket

Data

Procedures

mwings::ParsedPacketBase

Data

ParsedAppTwelitePacket

Data

ParsedAppIoPacket

Data

ParsedAppAriaPacket

Data

Magnet Event ID

ParsedAppCuePacket

Data

Acceleration Event ID

Magnet Event ID

ParsedAppPalAmbPacket

Data

ParsedAppPalMotPacket

Data

ParsedAppPalOpenClosePacket

Data

Magnet Event ID

ParsedAppUartAsciiPacket

Data

ParsedAppUartAsciiExtendedPacket

Data

ParsedActPacket

Data

mwings::CommandBase

Data

Procedures

AppTweliteCommand

Data

AppIoCommand

Data

AppPalNoticeCommand

Data

AppPalNoticeDetailedCommand

Data

AppPalNoticeEventCommand

Data

AppUartAsciiCommand

Data

AppPalNoticeRGBWColor

Data

Procedures

Enumerations

AppPalNoticeColor

AppPalNoticeBlinkSpeed

Other Data Types

Procedures

GetAppTweliteSerializedCommandPayloadSize()

GetAppAppPalNoticeSerializedCommandPayloadSize()

GetAppAppPalNoticeDetailedSerializedCommandPayloadSize()

GetAppAppPalNoticeEventSerializedCommandPayloadSize()

1.1.2 - Class List

1.1.2.1 - mwings::MWings Class

Constructor

MWings()

Arguments

Destructor

~MWings()

Public Member Functions

begin()

Arguments

Return Value

end()

Arguments

Return Value

update()

Arguments

Return Value

on() <BarePacket>

Arguments

`BarePacket`

`mwings::ParsedPacketBase`

`ParsedAppTwelitePacket`

`ParsedAppIoPacket`

`ParsedAppAriaPacket`

`ParsedAppCuePacket`

`ParsedAppPalAmbPacket`

`ParsedAppPalMotPacket`

`ParsedAppPalOpenClosePacket`

`ParsedAppUartAsciiPacket`

`ParsedAppUartAsciiExtendedPacket`

`ParsedActPacket`

`mwings::CommandBase`

`AppTweliteCommand`

`AppIoCommand`

`AppPalNoticeCommand`

`AppPalNoticeDetailedCommand`

`AppPalNoticeEventCommand`

`AppUartAsciiCommand`

`AppPalNoticeRGBWColor`

`AppPalNoticeColor`

`AppPalNoticeBlinkSpeed`

`GetAppTweliteSerializedCommandPayloadSize()`

`GetAppAppPalNoticeSerializedCommandPayloadSize()`

`GetAppAppPalNoticeDetailedSerializedCommandPayloadSize()`

`GetAppAppPalNoticeEventSerializedCommandPayloadSize()`

`MWings()`

`~MWings()`

`begin()`

`end()`

`update()`

`on()` <`BarePacket`>

`on()` <`ParsedAppTwelitePacket`>

`on()` <`ParsedAppIoPacket`>

`on()` <`ParsedAppAriaPacket`>

`on()` <`ParsedAppCuePacket`>

`on()` <`ParsedAppPalOpenClosePacket`>

`on()` <`ParsedAppPalAmbPacket`>

`on()` <`ParsedAppPalMotPacket`>

`on()` <`ParsedAppUartAsciiPacket`>

`on()` <`ParsedAppUartAsciiExtendedPacket`>

`on()` <`ParsedActPacket`>

`send()` <`uint8_t*, int, uint8_t`>

`send()` <`uint8_t*, int`>

`send()` <`uint8_t, uint8_t, uint8_t* int, uint8_t`>

`send()` <`uint8_t, uint8_t, uint8_t* int`>

`send()` <`AppTweliteCommand`>

`send()` <`AppIoCommand`>

`send()` <`AppPalNoticeCommand`>

`send()` <`AppPalNoticeDetailedCommand`>

`send()` <`AppPalNoticeEventCommand`>

`send()` <`AppPalUartAsciiCommand`>

`Twelite`

`Twelite()`

`close()`