# \<STG\_STD>

\<STG\_STD> は、最小限の設定項目を有した設定ビヘイビアです。

以下に設定画面例を提示します。

```
[CONFIG/MY_APP:0/SID=8102ECE3]
a: (0x1234ABCD) Application ID [HEX:32bit]
i: (         1) Device ID [1-100,etc]
c: (        13) Channel [11-26]
x: (      0x03) RF Power/Retry [HEX:8bit]
o: (0x00000000) Option 1 [HEX:32bit]
p: (0x00000000) Option 2 [HEX:32bit]
1: (0x00000000) Option 3 [HEX:32bit]
r: (0x00000000) Option 4 [HEX:32bit]

 [ESC]:Back [!]:Reset System [M]:Extr Menu                      
```

## 使用法

### 登録

```cpp
// use twelite mwx c++ template library
#include <TWELITE>
#include <NWK_SIMPLE>
#include <STG_STD> // interactive mode
```

上記のように `#include <STG_STD>` を追加します。

### setup() での読み出し

```cpp
uint32_t APP_ID;
uint8_t CHANNEL;
uint8_t LID;

void setup() {
   ...
   auto&& set = the_twelite.settings.use<STG_STD>();

   // call reload() before reading values.   
   set.reload();
   
   // read value
   APP_ID = set.u32appid();
   CHANNEL = set.u8ch();
   LID = set.u8devid();
   
   // apply them
	 the_twelite
		<< TWENET::appid(APP_ID)
		<< TWENET::channel(CHANNEL);
		
   auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();
   nwk	<< NWK_SIMPLE::logical_id(LID);
}
```

多くの場合、設定の読み出しは`setup()` 中の早い段階で行います。

上記の例はでは、まず`the_twelite.settings.use<STG_STD>()`により設定ビヘイビアを登録します。

{% hint style="info" %}
登録直後に、デフォルトのアプリケーションIDを変更するなど設定ビヘイビアの変更を行うことができますが、これは後述します。
{% endhint %}

つぎに`set.reload()`を呼び出し、実際にEEPROMからデータを読み出し、これを解釈します。自動で読み出さないことに注意してください。

`set.u32appid()`, `set.u8ch()`, `set.u8devid()`は各々アプリケーションIDの設定値、チャネルの設定値、論理デバイスIDの設定値を取得しています。ここでは変数に各設定値を格納しています。

{% hint style="info" %}
設定値を格納した内部データ構造は比較的複雑であるため、求める設定を得るまで、設計配列のデータ探索が必要になります。計算量を気にする場合は一旦設定値を別の変数に格納するようにしてください。
{% endhint %}

あとは、設定値を利用してアプリケーションIDやチャネルなどの値を反映します。

## 設定一覧

| 設定ID                             | 内容              |
| -------------------------------- | --------------- |
| `E_TWESTG_DEFSETS_APPID`         | アプリケーションID      |
| `E_TWESTG_DEFSETS_LOGICALID`     | 論理デバイスID (8bit) |
| `E_TWESTG_DEFSETS_CHANNEL`       | チャネル            |
| `E_TWESTG_DEFSETS_CHANNELS_3`    | チャネル（３ｃｈまで）     |
| `E_TWESTG_DEFSETS_POWER_N_RETRY` | 出力とリトライ回数       |
| `E_TWESTG_DEFSETS_OPTBITS`       | Option 1        |
| `E_TWESTG_DEFSETS_OPT_DWORD1`    | Option 2        |
| `E_TWESTG_DEFSETS_OPT_DWORD2`    | Option 3        |
| `E_TWESTG_DEFSETS_OPT_DWORD3`    | Option 4        |

`<STG_STD>`では、代表的な設定と自由に使える32bit値を４つ定義されています。これらは、ユーザが自由に利用できます。

{% hint style="info" %}

* STG\_STD>から読み出すだけでは設定は反映されません。
* 不要な項目を非表示にできます。
* 項目名や項目詳細を変更できます。
  {% endhint %}

## 設定ビヘイビアのカスタマイズ

設定ビヘイビアのカスタマイズは`.reload()`を行う前に全項目を行っておきます。

### アプリケーション名

```cpp
	auto&& set = the_twelite.settings.use<STG_STD>();
	set << SETTINGS::appname("MY_APP");
	...
	set.reload();
```

アプリケーション名はインタラクティブモードの先頭行に表示されます。

```
[CONFIG/MY_APP:0/SID=8102ECE3]
```

文字列ポインタを指定してください。内部でコピーを作らないようにしているため、ローカル変数を指定できません。

### アプリケーションIDのデフォルト値

```cpp
	auto&& set = the_twelite.settings.use<STG_STD>();
	set << SETTINGS::appid_default(0x13579be);
	...
	set.reload();
```

アプリケーションIDについては、デフォルト値を変更できます。

{% hint style="info" %}
デフォルト値の変更はアプリケーションIDのみ対応しています。
{% endhint %}

### 複数チャネル設定メニュー

```cpp
	auto&& set = the_twelite.settings.use<STG_STD>();
	set << SETTINGS::ch_multi();
	...
	set.reload();
```

`SETTINGS::ch_multi()` を指定すると、チャネル設定が複数指定になります。複数設定を行う場合、設定値の読み出しは`.u32chmask()`を用います。

### すぐに設定画面を表示する

```cpp
auto&& set = the_twelite.settings.use<STG_STD>();
	set << SETTINGS::open_at_start();
	...
	set.reload();
```

アプリケーションIDについては、デフォルト値を変更できます。

### 項目名、詳細の記述内容の変更

```cpp
const TWESTG_tsMsgReplace SET_MSGS[] = {
	{ E_TWESTG_DEFSETS_OPTBITS,    "オプション1", 
			"オプション１を設定してください" },
	{ E_TWESTG_DEFSETS_OPT_DWORD1, "オプション2",
			"オプション２を設定してください\r\nオプション２は云々" },
	{ E_TWESTG_DEFSETS_VOID } // terminator
};

setup() {
  auto&& set = the_twelite.settings.use<STG_STD>();
	set.replace_item_name_desc(SET_MSGS);
	...
```

項目名を別のモノに変更することが出来ます。上記の例ではUTF-8による日本語にしていますが、ターミナルの表示など条件がそろわないと適切には表示されません。

{% hint style="info" %}
TWELITE STAGEの場合、登録フォントの文字数を減らしている場合は、表示されない文字が出てくるかもしれません。必要な文字列が含まれるよう、再ビルドしてください。
{% endhint %}

この配列は最後に `{ E_TWESTG_DEFSETS_VOID }` で終端します。１番目のエントリは設定ID、２番目が項目名、３番目が設定入力時に表示される解説になります。`\r\n`により改行できます。

以下が設定IDの一覧になります。

| 設定ID                             | 内容              |
| -------------------------------- | --------------- |
| `E_TWESTG_DEFSETS_APPID`         | アプリケーションID      |
| `E_TWESTG_DEFSETS_LOGICALID`     | 論理デバイスID (8bit) |
| `E_TWESTG_DEFSETS_CHANNEL`       | チャネル            |
| `E_TWESTG_DEFSETS_CHANNELS_3`    | チャネル（３ｃｈまで）     |
| `E_TWESTG_DEFSETS_POWER_N_RETRY` | 出力とリトライ回数       |
| `E_TWESTG_DEFSETS_OPTBITS`       | Option 1        |
| `E_TWESTG_DEFSETS_OPT_DWORD1`    | Option 2        |
| `E_TWESTG_DEFSETS_OPT_DWORD2`    | Option 3        |
| `E_TWESTG_DEFSETS_OPT_DWORD3`    | Option 4        |

### 項目の削除

```cpp
  auto&& set = the_twelite.settings.use<STG_STD>();
	set.hide_items(E_TWESTG_DEFSETS_OPT_DWORD2, E_TWESTG_DEFSETS_OPT_DWORD3);
```

不要な項目の削除を行います。

## メソッド

### reload()

```cpp
	auto&& set = the_twelite.settings.use<STG_STD>();
	set << SETTINGS::appname(APP_NAME)
		  << SETTINGS::appid_default(DEF_APP_ID)
   		<< SETTINGS::open_at_start();
   
	set.reload();
```

設定を読み込みます。すべてのカスタマイズが終わってから実行します。

## メソッド （データ読み出し）

データの読み出しは以下のメソッドを呼び出します。

{% hint style="warning" %}
読み出し前に必ず`.reload()`を呼び出してください。
{% endhint %}

| メソッド                   | 内容                                              |
| ---------------------- | ----------------------------------------------- |
| `uint32_t u32appid()`  | アプリケーションID                                      |
| `uint8_t u8devid()`    | 論理デバイスID                                        |
| `uint8_t u8ch()`       | 設定チャネル (11..26)                                 |
| `uint32_t u32chmask()` | チャネル設定マスク (ビットマスクで指定、13 なら 1UL << 13 にビットを設定する) |
| `uint8_t u8power()`    | 出力設定 (0..3)                                     |
| `uint8_t u8retry()`    | リトライ数                                           |
| `uint32_t u32opt1()`   | オプション１                                          |
| `uint32_t u32opt1()`   | オプション２                                          |
| `uint32_t u32opt1()`   | オプション３                                          |
| `uint32_t u32opt1()`   | オプション４                                          |

{% hint style="info" %}
内部では、構造体配列を線形探索して設定IDに合致する設定構造体を探索しており、オーバーヘッドがあります。頻繁に参照される設定値は一旦別の変数にコピーして使用してください。
{% endhint %}