# MCSDataChannel 相關類別
藉由繼承自 MCSDataChannel 類別的資料通道實體，可用來與 MCS 伺服器上對應的資料通道進行傳送與接收資料點的操作。\
例如下例的開/關控制器通道：
該通道可被表示為一個 **MCSControllerOnOff** 類別的實體：
```
MCSControllerOnOff channelOnOff("channel_id_1");
device.addChannel(channelOnOff); // device is an instance of MCSDevice or MCSLiteDevice.
device.connect();
bool controllerValue = channel.value();
```
雖然隨著種類不同而有不一樣的資料格式，但每種資料通道都提供了 **set()** 與 **value()** 這兩個函式用來存取資料數值。下面章節將列出在 Arduino sketch 中所有可用的資料通道類別。
資料通道有兩個主要的子類別：**控制器通道**類別與**顯示器通道**類別。例如 MCSControllerOnOff 和 MCSControllerInteger 的**控制器通道**用來表示 MCS 上的控制器通道；而 MCSDisplayFloat 和 MCSDisplayString **顯示器通道**則對應到 MCS 上的顯示器通道。
建構函式
\> MCSDataChannel()
{% tabs %}
{% tab title="MCSDataChannel()" %}
產生一個可加進 MCSDevice 或 MCSLiteDevice 裝置實體的資料通道。
**Syntax**
MCSControllerOnOff *dataChannel*(data\_channel\_ID)
MCSDisplayOnOff *dataChannel*(data\_channel\_ID)
MCSControllerCategory *dataChannel*(data\_channel\_ID)
MCSDisplayCategory *dataChannel*(data\_channel\_ID)
MCSControllerInteger *dataChannel*(data\_channel\_ID)
MCSDisplayInteger *dataChannel*(data\_channel\_ID)
MCSControllerFloat *dataChannel*(data\_channel\_ID)
MCSDisplayFloat *dataChannel*(data\_channel\_ID)
MCSControllerHex *dataChannel*(data\_channel\_ID)
MCSDisplayHex *dataChannel*(data\_channel\_ID)
MCSControllerString *dataChannel*(data\_channel\_ID)
MCSDisplayString *dataChannel*(data\_channel\_ID)
MCSControllerGPS *dataChannel*(data\_channel\_ID)
MCSDisplayGPS *dataChannel*(data\_channel\_ID)
MCSControllerGPIO *dataChannel*(data\_channel\_ID)
MCSDisplayGPIO *dataChannel*(data\_channel\_ID)
MCSControllerPWM *dataChannel*(data\_channel\_ID)
MCSDisplayPWM *dataChannel*(data\_channel\_ID)
MCSControllerAnalog *dataChannel*(data\_channel\_ID)
**Parameters**
data\_channel\_ID：在 MCS 伺服器上建立的資料通道 channel id。
**Returns**
*dataChannel* 即為繼承自 **MCSDataChannel** 類別的子類別實體。
{% endtab %}
{% endtabs %}
### MCSDataChannel 函式
所有的資料通道種類皆支援下列函式：
\> updated()
\> valid()
\> value()
{% tabs %}
{% tab title=" updated()" %}
檢查資料通道是否有接收到新的資訊點。在進行檢查之前，開發者需要先呼叫 *device*.process() 函式處理來自 MCS 伺服器的指令。若該資料通道有多次更新，則只有最後 (即最新的) 一筆資料會被保留下來。
**Syntax**
*dataChannel*.updated()
**Parameters**
無
**Returns**
若此資料通道有新的資料點更新，則回傳布林值 true；反之則回傳 false。
{% endtab %}
{% tab title="valid()" %}
檢查該資料通道欲接收 / 傳送的值是否為有效值。
**Syntax**
dataChannel.valid()
**Parameters**
無
**Returns**
若此資料通道的值為有效值，則回傳布林值 true；反之則回傳 false。
{% endtab %}
{% tab title="value()" %}
取得此資料通道的數值 (MCSControllerGPS 與 MCSDisplayGPS 類別除外)。
**Syntax**
*dataChannel*.value()
**Parameters**
無
**Returns**
該資料通道的值。其資料類型依各資料通道而定，例如整數、浮點數、字串等。
{% endtab %}
{% endtabs %}
### 顯示器通道函式
\> set()
{% tabs %}
{% tab title="set()" %}
設定此顯示器通道的數值。
**Syntax**
dataChannel.set(value)
MCSDisplayPWM.set(value, period)
MCSDisplayGPS.set(latitude, longitude, altitude)
**Parameters**
dataChannel：繼承自 MCSDataChannel 類別的實體，如 MCSDisplayOnOff 和 MCSDisplayCategory...。
MCSDisplayPWM：MCSDisplayPWM 類別的實體。
MCSDisplayGPS：MCSDisplayGPS 類別的實體。
value：欲設定至該資料通道的值。其資料類型依各資料通道而定，例如整數、浮點數、字串等。
period：指定給 PWM 資料通道的整數週期值，其值為 PWM 頻率的倒數。
latitude、longitude、altitude：GPS 資料通道的座標值，其資料類型為浮點數。
**Returns**
若該資料通道的數值被成功更新至 MCS 伺服器，則回傳布林值 true；反之則回傳 false。
{% endtab %}
{% endtabs %}
### 控制器通道函式
\> setServerValue()
{% tabs %}
{% tab title="setServerValue()" %}
設定此控制器通道的數值。
**Syntax**
controllerChannel.setServerValue(value)
MCSControllerGPS.setServerValue(latitude, longitude, altitude)
**Parameters**
controllerChannel：繼承自 MCSDataChannel 類別的實體，如 MCSControllerOnOff 和 MCSControllerCategory...。
MCSControllerGPS：MCSControllerGPS 類別的實體。
value：欲設定至該資料通道的值。其資料類型依各資料通道而定，例如整數、浮點數、字串等。
| 通道類別 | 資料類型 |
| --------------------- | ----------- |
| MCSControllerOnOff | bool |
| MCSControllerFloat | float |
| MCSControllerInteger | int |
| MCSControllerAnalog | int |
| MCSControllerGPIO | int |
| MCSControllerHex | long |
| MCSControllerCategory | String |
| MCSControllerString | String |
| MCSControllerPWM | MCSPWMValue |
| MCSControllerGPS | MCSGPSValue |
latitude、longitude、altitude：GPS 資料通道的座標值，其資料類型為浮點數。
Returns
若該資料通道的數值被成功更新至 MCS 伺服器，則回傳布林值 true；反之則回傳 false。
{% endtab %}
{% endtabs %}
### MCSControllerPWM 控制器通道函式
針對 **PWM 控制器**資料通道，提供了：
\> dutyCycle()
\> period()
{% tabs %}
{% tab title=" dutyCycle()" %}
取得此 PWM 控制器通道的 duty cycle 值。
**Syntax**
MCSControllerPWM.dutyCycle()
**Parameters**
MCSControllerPWM：MCSControllerPWM 類別的實體。
**Returns**
該 PWM 控制器通道的 duty cycle 設定值 (在 MCS 控制介面顯示為 value)，其資料類型為整數。
{% endtab %}
{% tab title=" period()" %}
取得此 PWM 控制器通道的週期值。
**Syntax**
MCSControllerPWM.period()
**Parameters**
MCSControllerPWM：MCSControllerPWM 類別的實體。
**Returns**
該 PWM 控制器通道的週期設定值，其資料類型為整數。
{% endtab %}
{% endtabs %}
### GPS 通道函式
針對 **GPS 控制器**與 **GPS 顯示器**資料通道，提供了以下函式供查詢經緯度及高度資訊。
\> latitude()
\> longitude()
\> altitude()
{% tabs %}
{% tab title=" latitude()" %}
取得此 GPS 控制器通道的緯度值。
**Syntax**
MCSControllerGPS.latitude()
**Parameters**
MCSControllerGPS：MCSControllerGPS 類別的實體。
**Returns**
該 GPS 控制器通道的緯度值，其資料類型為浮點數。
{% endtab %}
{% tab title=" longitude()" %}
取得此 GPS 控制器通道的經度值。
**Syntax**
MCSControllerGPS.longitude()
**Parameters**
MCSControllerGPS：MCSControllerGPS 類別的實體。
**Returns**
該 GPS 控制器通道的經度值，其資料類型為浮點數。
{% endtab %}
{% tab title=" altitude()" %}
取得此 GPS 控制器通道的高度值。
**Syntax**
MCSControllerGPS.altitude()
**Parameters**
MCSControllerGPS：MCSControllerGPS 類別的實體。
**Returns**
該 GPS 控制器通道的高度值，其資料類型為浮點數。
{% endtab %}
{% endtabs %}
### Gamepad 控制器通道函式
**Gamepad** 為用來表示按鍵資訊的**控制器**通道，包含兩種按鍵狀態：
* 哪顆鍵 (**BTN\_UP**、**BTN\_DOWN**、**BTN\_LEFT**、**BTN\_RIGHT**、**BTN\_A**、**BTN\_B**) 被操作，以及
* 該按鍵是被按下 (**BTN\_PRESSED**) 或放開 (**BTN\_RELEASED**)。
可表示的按鍵 enumeration 如下：
```
enum MCSGamePadButton{
BTN_UP = 1,
BTN_DOWN,
BTN_LEFT,
BTN_RIGHT,
BTN_A,
BTN_B,
BTN_INVALID
};
```
表示按壓狀態的 enumeration 為：
```
enum MCSGamePadButtonEvent{
BTN_PRESSED = 1,
BTN_RELEASED = 0,
BTN_NO_EVENT = -1
};
```
因此可透過 *button* 與 *event* 欄位對從 **value()** 函式所取得的資訊進行解讀：
```
if(BTN_UP == gamepadChannel.value().button &&
BTN_PRESSED == gamepadChannel.value().event)
{
// Do something when the "UP" key is pressed...
}
```
透過下列函式，亦可取得按鍵資訊與按壓狀態：
\> button()
\> event()
{% tabs %}
{% tab title=" button()" %}
取得目前正在作用的按鍵。
**Syntax**
MCSControllerGamePad.button()
**Parameters**
MCSControllerGamePad：MCSControllerGamePad 類別的實體。
**Returns**
正在作用按鍵的 **MCSGamePadButton** enumeration 值。目前支援的按鍵種類如下：
```
enum MCSGamePadButton{
BTN_UP = 1,
BTN_DOWN,
BTN_LEFT,
BTN_RIGHT,
BTN_A,
BTN_B,
BTN_INVALID
};
```
{% endtab %}
{% tab title="event()" %}
取得目前作用按鍵的狀態 (被按下或是放開)。
**Syntax**
MCSControllerGamePad.button()
**Parameters**
MCSControllerGamePad：MCSControllerGamePad 類別的實體。
**Returns**
目前作用按鍵的狀態 (資料類型為 **MCSGamePadButtonEvent**)。提供的資訊種類有：
```
enum MCSGamePadButtonEvent{
BTN_PRESSED = 1,
BTN_RELEASED = 0,
BTN_NO_EVENT = -1
};
```
{% endtab %}
{% endtabs %}