1 / 26

TWEFMT

パケット定義

書式を解釈して得られたデータ列は、受信したパケット情報が含まれます。ここでは、このデータ列のことをパケットデータと呼びます。

パケットデータはTwePacketクラスで表現されます。TwePacketクラスのデータを解釈することで、その種別を判定し、各アプリケーションや接続ハードウェアに応じたデータ構造となります。TwePacketクラスは基底クラスでさらにパケット種別ごとの派生クラスとなります。

このオブジェクトは無線パケットのデータ量に準じたメモリ領域を消費し、また、アプリケーションでは多数のパケットを保持することも考えられます。メモリ管理を簡略化するためTwePacketをスマートポインタstd:shared_ptr<TwePacket>にて管理します。このスマートポインタをspTwePacketにtypedefしています。

以下に、TWELITE PALのパケットデータの場合のクラス関係を示します。TwePacketPalの基底クラスの一つDataPalはTWELITE PAL特有のデータを格納しています。TWELITE PALには、さらに接続されるセンサーパルによって格納すべきデータが異なります。TwePacketPalからさらにPalAmbやPalMotを生成します。例えばPalAmbには温室センサーの値や照度センサーの値が格納されます。このTwePacketPalをスマートポインタspTwePacketという形に生成するのがnewTwePacket()です。

    [spTwePacket] ←(生成)- newTwePacket()
          ◆ 
          ｜(shared_ptr)
          ｜
      [TwePacket]    [DataPal]
              ↑        ↑
            [TwePacketPal] -(生成)-> [PalAmb], [PalMot], ...

spTwePacket型はスマートポインタですので、オブジェクトのコピー渡しによる記述を行うことで、コピーのオーバーヘッドを最小にしつつ、メモリーの管理を自動化できます。以下の例はパケットの履歴を管理する単純なクラスです。

struct _pkt_hist {
	spTwePacket _pkt[16]; // パケットの履歴
	int _i;

	_pkt_hist() : _i(-1), _pkt{} {}
	void add_entry(spTwePacket p) { _pkt[++_i & 0xF] = p; }
	spTwePacket get_entry(int i) { return _pkt[(i + _i) & 0xF]; }
} pkt_hist;

void loop() {
  spTwePacket pkt, pkt_last;
  
  // 新たなパケットオブジェクト
  pkt = newTwePacket(p, len);
  pkt_hist.add_entry(pkt); // 履歴に保存する

  // ひとつ前のパケットオブジェクト
  pkt_last = pkt_hist.get_entry(-1);
}

TwePacket, spTwePacket

パケットオブジェクト

パケットデータは種別によってデータ構造が違いますが、様々な種類のパケットを一元管理するための基底クラスです。

class TwePacket;
typedef std::shared_ptr<TwePacket> spTwePacket;

spTwePacket はメモリ管理のためのスマートポインタです。std::shared_ptrを用いています。

TwePacketクラスは、パケットデータのパケット種別の管理を行います。また、パケットデータの解釈を行うための仮想関数parse()メソッドを定義しています。パケット特有のデータ構造に基づく解釈やデータの保存等の取り扱いは、派生クラスに実装します。

メソッド

TwePacket() - コンストラクタ

TwePacket(E_PKT ptyp = E_PKT::PKT_ERROR)

デフォルトでは、未解釈状態として E_PKT::PKT_ERROR で初期化します。

~TwePacket() - デストラクタ

virtual ~TwePacket()

get_type()

E_PKT get_type()

パケットの種別をE_PKT型で返します。

parse()

virtual E_PKT parse(uint8_t* p, uint8_t u8len)

パケットデータのバイト列を与えて、パケットデータを解釈する。

派生クラスで、そのパケットに対応するデータ構造を解釈するための実装を行います。

戻り値は E_PKT型で、成功時は解釈されたパケット種別を、エラー時に E_PKT::PKT_ERROR を返します。

E_PKT

パケット種別定義

以下のパケットに対応します。

App_Wings の親機で出力されるアスキー書式に対応します。

idenify_packet_type()

パケット種別判定

パケットデータのバイト列を入力として、パケットの種別を判定します。また既に生成済みのspTwePacketオブジェクトの種別を返します。戻り値はE_PKTです。

E_PKT identify_packet_type(uint8_t* p, uint8_t u8len)
E_PKT identify_packet_type(SmplBuf_Byte& sbuff)

E_PKT identify_packet_type(spTwePacket& sp)

newTwePacket()

パケットデータの解釈とオブジェクト生成

パケットデータのバイト列を入力として、パケット種別の判定と、種別に応じたspTwePacketオブジェクトを生成します。

spTwePacket newTwePacket(
		uint8_t* p,
		uint8_t u8len,
		E_PKT eType = E_PKT::PKT_ERROR)

spTwePacket newTwePacket(
		TWEUTILS::SmplBuf_Byte& sbuff,
		E_PKT eType = E_PKT::PKT_ERROR)

事前にidentify_packet_type()を用いてパケットの種別E_PKTが特定できている場合はeTypeを与えます。

戻り値はspTwePacketです。

refTwePacket()

spTwePacketオブジェクトの参照

本関数はspTwePacketオブジェクトをTwePacket&として参照します。

TwePacket& refTwePacket(spTwePacket& p)

//例
  auto&& pkt = newTwePacket(p, len); // パケットの生成
  
  if (refTwePacket(pkt).get_type() == E_PKT::PKT_TWELITE) {
    // App_Twelite の処理
  }

この関数は、->演算子や*演算子を極力使用しない方針でライブラリを設定しているため、スマートポインタの参照を行うために用意しています。

上記の判定式を(pkt && pkt->get_type() == E_PKT::PKT_TWELITE)と記述しても同じ判定が得られます。

Packet Types

パケット種別ごとの定義

対応するパケット種別はE_PKT定義を参照してください。

TwePacketAppIO

TwePacketAppIOクラスは、標準アプリApp_IOのシリアルメッセージ(0x81)を解釈したものです。

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

パケットデータ内の諸情報はparse()実行後にDataTweliteに格納されます。

spTwePacketからの参照

TwePacketAppIO& refTwePacketAppIO(spTwePacket& p)

spTwePacketオブジェクトからTwePacketAppIOオブジェクトを参照します。spTwePacketにTwePacketAppIO以外が格納されている場合は、未解釈のオブジェクトを戻します。

実行例

if (parse_ascii) { // アスキー形式のパーサーの解釈完了
  auto&& pkt = newTwePacket(parse_ascii.get_payload());
		
	if (identify_packet_type(pkt) == E_PKT::PKT_APPIO) { // パケット解釈成功時
	  auto&& x = refTwePacketAppIO(pkt);
		  
		the_screen // LCDスクリーン上のターミナルに情報を表示
				<< printfmt(":Lq=%d:Ad=%08X", x.u8lqi, x.u32addr_src)
				<< printfmt(":ID=%02X", x.u8addr_src)
				<< printfmt(":DI=%08b", x.DI_mask)
				;
	}
}

DataAppIO

TwePacketAppIOのデータ部分。

struct DataAppIO {
		//送信元のシリアル#
		uint32_t u32addr_src;
		
		// 送信元の論理ID
		uint8_t u8addr_src;

		// 宛先の論理ID
		uint8_t u8addr_dst;

		// 送信時のタイムスタンプ
		uint16_t u16timestamp;

		// 低レイテンシ送信時のフラグ
		bool b_lowlatency_tx;

		// リピート中継回数
		uint16_t u8rpt_cnt;

		// LQI値
		uint16_t u8lqi;

		// DIの状態ビットマップ (LSBから順にDI1,2,3,4,...)
		uint8_t DI_mask;

		// DIのアクティブ(使用なら1)ビットマップ(LSBから順にDI1,2,3,4,...)
		uint8_t DI_active_mask;
		
		// DIが割り込み由来かどうかのビットマップ(LSBから順にDI1,2,3,4,...)
		uint16_t DI_int_mask;
};

TwePacketPal

TWELITE PALのパケット

TwePacketPalクラスは、TWELITE PALのパケットデータを解釈したものです。このクラスはTWELITE PAL（センサーデータなど上り方向）共通に取り扱います。

PAL共通データはに定義されています。

PALの各センサー基板特有のデータを取り出すためのジェネレータ関数を用意しています。

spTwePacketからの参照

spTwePacketオブジェクトからTwePacketPalオブジェクトを参照します。spTwePacketにTwePacketPal以外が格納されている場合は、未解釈のオブジェクトを戻します。

実行例

パケットデータ定関数

has_palEvent()

パケットにイベント情報が含まれるかを判定します。

get_PalDataType()

has_data_info()

パケットプロパティ（パケットの補助情報）が含まれているか判定します。含まれている場合はPalDataInfoで定義されるメンバーにアクセスできます。

is_data_source_timer()

パケットプロパティが存在する場合に呼び出しは有効。タイマー由来からの送信の場合trueを返します。

ジェネレータ関数

センサーPALの各種データを取り出すためのジェネレータ関数です。

get_PalMag()

get_PalAmb()

get_PalMot()

get_PalEvent()

.is_PalEvent()がtrueの場合PalEvent(PALイベント)を取り出します。

DataPal

PAL共通データ

PALは接続されるセンサーなどによってパケットデータ構造が異なりますが、DataPalでは共通部のデータ構造を保持します。

PALのパケットデータ構造は大まかに２つのブロックからなり、全てのPAL共通部と個別のデータ部になります。個別のデータ部は、パケットの解釈を行わずそのまま格納しています。取り扱いを単純化するため32バイトを超えるデータは動的に確保するuptr_snsdataに格納します。

個別のデータ部は、PalBaseをベースクラスに持つ構造体に格納されます。この構造体は、TwePacketPalに定義されるジェネレータ関数により生成されます。

u8pkt_typeが0の時はPalDataInfoデータ構造が付与された形式となります。比較的複雑な情報を格納するための形式です。1の場合はPAL基板ごとに決められた標準的な形式でデータが格納されています。

E_PAL_PCB

PAL基板種別

下記のPAL基板に対応します。

E_PAL_DATA_TYPE

TWELITE PAL/CUEのパケットはTwePacketPal::get_PalDataType()により、どういった形式で格納されているかを判定します。

TwePacketPal::u8palpcbによる判定の場合、より新しい形式に対応できません。

MAG/AMB/MOTの3種類の場合、下記例の^7の位置にある値(PAL基板種別)のMSB(0x80)が設定されている場合に限りu8palpcbによる判定からget_PalMag(),get_PalAmb() ,get_PalMot() によりオブジェクトを取り出すことが出来ます。

E_CAUSE

パケット送信要因。PalDataInfo::e_data_causeで使用されます。

PalEvent

PALイベントは、センサーなどの情報を直接送るのではなく、センサー情報を加工し一定の条件が成立したときに送信される情報です。例えば加速度センサーの静止状態から一定以上の加速度が検出された場合などです。

イベントデータが存在する場合はTwePacketPalの.is_PalEvent()がtrueになることで判定でき、.get_PalEvent()によりPalEventデータ構造を得られます。

PalDataInfo

PAL/CUEのパケットがどのような原因で送信されたかなどを付加する補助情報です。例えばタイマー送信かセンサーの発報によるものかなどの情報が含まれます。が本構造体を継承しており単独では使用しません。

PalBase

PALセンサー共通データ

PALの各センサーのデータ構造体はすべてPalBaseを継承します。センサーデータの格納状況u32StoredMaskの情報が含まれます。

	struct PalBase {
		uint32_t u32StoredMask;
	};

派生構造体に定義されるSTORE_COMP_MASKとu32StoreMaskが一致すれば、全てのセンサーのデータが適切に解釈され、格納されていることになります。

PalMag

開閉センサーパル(MAG)のセンサーデータ

PalAmb

環境センサーパル(AMB)のセンサーデータ

struct PalAmb : public PalBase {
	const uint8_t U8VARS_CT = 4; // センサー数
	const uint32_t STORE_COMP_MASK = (1 << U8VARS_CT) - 1; // 全コンプマスク

  uint16_t u16Volt; // 電源電圧
	int16_t i16Temp;  // 温度 (x100)
	uint16_t u16Humd; // 湿度 (x100 %)
	uint32_t u32Lumi; // 照度 (lux相当)
};

PalMot

動作センサーパル(MOT)のセンサーデータ

struct PalMot : public PalBase {
	const uint8_t U8VARS_CT = 17; // センサー数
	const uint32_t STORE_COMP_MASK = 3; // 電圧と加速度サンプル１あればコンプとする

  uint16_t u16Volt; // 電源電圧
  
	uint8_t u8samples; // 格納サンプル数
	int16_t i16X[16];  // X軸 (ミリG)
	int16_t i16Y[16];  // Y軸
	int16_t i16Z[16];  // Z軸
};

※ パケット間の各サンプルの連続性を確認するには、パケットのシーケンス番号の抜けが無いことを確認してください。

TwePacketActStd

TwePacketActStdクラスは、アクト(Act)のサンプルなどの無線パケットを親機・中継器アプリApp_Wingsで受信したときの形式です。(App_UARTの拡張形式とほぼ同じになります）

class TwePacketActStd : public TwePacketAppUART

spTwePacketからの参照

TwePacketActStd& refTwePacketActStd(spTwePacket& p)

spTwePacketオブジェクトからTwePacketActStdオブジェクトを参照します。spTwePacketにTwePacketActStd以外が格納されている場合は、未解釈のオブジェクトを戻します。

実行例

if (parse_ascii) { // アスキー形式のパーサーの解釈完了
  auto&& pkt = newTwePacket(parse_ascii.get_payload());
    
    if (identify_packet_type(pkt) == E_PKT::PKT_ACT_STD) { // パケット解釈成功時
      auto&& x = refTwePacketActStd(pkt);
      
  		the_screen // LCDスクリーン上のターミナルに情報を表示
  				<< printfmt(":Lq=%d:Ad=%08X", x.u8lqi, x.u32addr_src)
  				<< printfmt(":ID=%02X", x.u8addr_src)
  				;
  
      if (x.payload.length() > 5) {
        auto p = act.payload.begin();
        
        // 先頭４バイトはActコードで無線パケット先頭に設定した４文字アルファベット
        the_screen << ":FOURCC=";
        for(int i = 0; i < 4; ++i, ++p)
            the_screen << printfmt("%c", *p);
        
        // 残りはHEXで表示（Actコードごとによって違う)
        the_screen << ":DATA=";
        for(; p != x.payload.end(); ++p) {
    			the_screen << printfmt("%02X", *p);
    		}
      }
    }
  }
}

DataAppUART (Act用)

TwePacketActStdのデータ部。（書式はApp_UARTと同一でDataAppUART型を流用しています）

struct DataAppUART {
		/**
		 * 送信元のアドレス
		 */
		uint32_t u32addr_src;

		/**
		 * 送信先のアドレス
		 */
		uint32_t u32addr_dst;

		/**
		 * 送信元の論理ID
		 */
		uint8_t u8addr_src;

		/**
		 * 宛先の論理ID
		 */
		uint8_t u8addr_dst;

		/**
		 * LQI値
		 */
		uint8_t u8lqi;

		/**
		 * 未使用
		 */
		uint8_t u8response_id;

		/**
		 * データ部の長さ
		 */
		uint16_t u16paylen;

		/**
		 * データ部配列
		 */
		TWEUTILS::SmplBuf_Byte payload;
	};

TwePacketTwelite

TwePacketTweliteクラスは、標準アプリApp_Tweliteの0x81コマンドを解釈したものです。

class TwePacketTwelite : public TwePacket, public DataTwelite { ... };

パケットデータ内の諸情報はparse()実行後にDataTweliteに格納されます。

spTwePacketからの参照

TwePacketTwelite& refTwePacketTwelite(spTwePacket& p)

spTwePacketオブジェクトからTwePacketTweliteオブジェクトを参照します。spTwePacketにTwePacketTwelite以外が格納されている場合は、未解釈のオブジェクトを戻します。

実行例

if (parse_ascii) { // アスキー形式のパーサーの解釈完了
  auto&& pkt = newTwePacket(parse_ascii.get_payload());
		
	if (identify_packet_type(pkt) == E_PKT::PKT_TWELITE) { // パケット解釈成功時
	  auto&& x = refTwePacketTwelite(pkt);
		  
		the_screen // LCDスクリーン上のターミナルに情報を表示
				<< printfmt(":Lq=%d:Ad=%08X", x.u8lqi, x.u32addr_src)
				<< printfmt(":ID=%02X", x.u8addr_src)
				<< printfmt(":DI=%04b", x.DI_mask)
				;
	}
}

DataTwelite

App_Twelite データ

TwePacketTweliteのデータ部分。

struct DataTwelite {
		//送信元のシリアル#
		uint32_t u32addr_src;
		
		// 送信元の論理ID
		uint8_t u8addr_src;

		// 宛先の論理ID
		uint8_t u8addr_dst;

		// 送信時のタイムスタンプ
		uint16_t u16timestamp;

		// 低レイテンシ送信時のフラグ
		bool b_lowlatency_tx;

		// リピート中継回数
		uint16_t u8rpt_cnt;

		// LQI値
		uint16_t u8lqi;

		// DIの状態 (true がアクティブ Lo,GND)
		bool DI1, DI2, DI3, DI4;
		// DIの状態ビットマップ (LSBから順にDI1,2,3,4)
		uint8_t DI_mask;

		// DIアクティブならtrue (過去にアクティブになったことがある)
		bool DI1_active, DI2_active, DI3_active, DI4_active;
		// DIのアクティブビットマップ(LSBから順にDI1,2,3,4)
		uint8_t DI_active_mask;

		// モジュールの電源電圧[mV]
		uint16_t u16Volt;

		// AD値 [mV]
		uint16_t u16Adc1, u16Adc2, u16Adc3, u16Adc4;
		// ADがアクティブ（有効）なら 1 になるビットマップ (LSBから順にAD1,2,3,4)
		uint8_t Adc_active_mask;
};

TwePacketAppUart

TwePacketAppUartクラスは、App_UARTの拡張書式を親機・中継器アプリApp_Wingsで受信したときの形式です。

class TwePacketAppUART : public TwePacket, public DataAppUART

spTwePacketからの参照

TwePacketAppUART& refTwePacketAppUART(spTwePacket& p)

spTwePacketオブジェクトからTwePacketAppUARTオブジェクトを参照します。spTwePacketにTwePacketAppUART以外が格納されている場合は、未解釈のオブジェクトを戻します。

実行例

if (parse_ascii) { // アスキー形式のパーサーの解釈完了
  auto&& pkt = newTwePacket(parse_ascii.get_payload());
    
    if (identify_packet_type(pkt) == E_PKT::PKT_APPUART) { // パケット解釈成功時
      auto&& x = refTwePacketAppUART(pkt);
      
  		the_screen // LCDスクリーン上のターミナルに情報を表示
  				<< printfmt(":Lq=%d:Ad=%08X", x.u8lqi, x.u32addr_src)
  				<< printfmt(":ID=%02X", x.u8addr_src)
  				;
  
      if (x.payload.length() > 0) {
        auto p = act.payload.begin();
        
        // HEXで表示
        the_screen << ":DATA=";
        for(; p != x.payload.end(); ++p) {
    			the_screen << printfmt("%02X", *p);
    		}
      }
    }
  }
}

DataAppUART

TwePacketAppUartのデータ部。

struct DataAppUART {
		/**
		 * 送信元のアドレス
		 */
		uint32_t u32addr_src;

		/**
		 * 送信先のアドレス
		 */
		uint32_t u32addr_dst;

		/**
		 * 送信元の論理ID
		 */
		uint8_t u8addr_src;

		/**
		 * 宛先の論理ID
		 */
		uint8_t u8addr_dst;

		/**
		 * LQI値
		 */
		uint8_t u8lqi;

		/**
		 * 未使用
		 */
		uint8_t u8response_id;

		/**
		 * データ部の長さ
		 */
		uint16_t u16paylen;

		/**
		 * データ部配列
		 */
		TWEUTILS::SmplBuf_Byte payload;
	};