ラズベリーパイ用高精度A/D変換モジュール「ADPi Pro」のadpictl コマンドのチュートリアル

# はじめに
メカトラックス社のラズベリーパイ用高精度A/D変換モジュール「ADPi Pro」のadpictl コマンドの使用方法について説明します。adpictl コマンドは、ADPi を動作させるツール[adpi-utils](https://github.com/mechatrax/adpi-utils)の一部として提供されます。


# ADPi Proのadpictl コマンドのセットアップ
adpictl コマンドの構文は、ADPi Proが使用するSPI デバイスとIIO サブシステムの二つのインタフェース共に共通で、フォルダ「/usr/sbin/adpictl」にコマンドがセットアップされます。セットアップは、SPI デバイスの場合、[SPIを用いたラズベリーパイ用高精度A/D変換モジュール「ADPi Pro」のセットアップ](https://qiita.com/TomoSoft/items/8aee48e685db8ffab3ca)、IIOサブシステムの場合、　[IIOサブシステムを用いたラズベリーパイ用高精度A/D変換モジュール「ADPi Pro」のセットアップ](https://qiita.com/TomoSoft/items/7eea3e7483ff8b0df82d)をそれぞれ参照してください。


# adpictl コマンドのチュートリアル
adpictl コマンドは、ADPi に対してサンプリング周波数やゲイン倍率等の設定/表示などを行うコマンドで、セットアップを行うことにより、フォルダ「/usr/sbin/adpictl」にコマンドが作成されます。コマンドラインの構文を次に示します。

```
adpictl [OPTION] COMMAND ...
  COMMAND： サンプリング周波数等の表示および設定
  OPTION：  デバイス等の構成の設定
```

## COMMAND に指定可能な引数
COMMANDにより、設定されているサンプリング周波数等の表示、サンプリング周波数等の再設定、ヘルプやバージョンの表示が、あらかじめ決められたコマンドの構文を用いることで実行できます。

### 設定されたデータの表示「get PARAMETER」
次の構文に従い、指定した PARAMETER を使用して、ADPi Proに設定された次のデータを表示します。

```
adpictl get PARAMETER
  PARAMETER： サンプリング周波数「frequency」 
              ゲイン倍率「gain」 
              電源端子の出力状態「output」 
              分解能「scale」 
              温度「temperature」 
              測定した電圧「voltage」 
```

#### サンプリング周波数「frequency」
設定されているサンプリング周波数を、単位「Hz」で表示します。

```
$ adpictl get frequency
470
```

#### ゲイン倍率「gain」
設定されている電圧レンジに対応したゲイン倍率を表示します。

```
$ adpictl get gain
1
```

#### 電源端子の出力状態「output」
接続先チャンネルの電源端子の出力状態を表示します。なお、表示するチャンネル番号をパラメータとして与えます。

```
$ adpictl get output 1
off
$ adpictl get output 2
off
$ adpictl get output 3
off
$ adpictl get output 4
off
```

#### 分解能「scale」
設定されている電圧レンジに対応した分解能を単位「mV」で表示します。

```
$ adpictl get scale
0.000596040
```
#### 温度「temperature」 
 ADC 内部の温度を表示します。 単位は ℃ です。

```
$ adpictl get temperature
30.073874834
```
#### 電圧測定「voltage」
接続先 CH の測定した電圧を単位「mV」で表示します。なお、表示するチャンネル番号をパラメータとして与えます。

```
$ adpictl get voltage 1
311.746205160
$ adpictl get voltage 2
312.664702800
$ adpictl get voltage 3
312.180718320
$ adpictl get voltage 4
311.541763440
```

### データの設定「set PARAMETER ...　」
次の構文に従い、指定した PARAMETER を使用して、ADPi Proに次のデータを設定します。

```
adpictl set PARAMETER ...
  PARAMETER： サンプリング周波数「frequency」 
              ゲイン倍率「gain」 
              電源端子の出力状態「output」 
              分解能「scale」 
```


#### サンプリング周波数「frequency」
サンプリング周波数を単位「Hz」で設定します。設定できるサンプリング周波数を次に示します。

- 設定できるサンプリング周波数：　`470 242 123 62 50 39 33 19 17 16 12 10 8 6 4`　

```
$ adpictl set frequency 242
$ adpictl get frequency
242
$ adpictl set frequency 470
$ adpictl get frequency
470
```


#### ゲイン倍率「gain」
電圧レンジに対応したゲイン倍率を設定します。設定できるゲイン倍率を次に示します。

- 設定できるゲイン倍率：　`1    128  16   2    32   4    64   8`

```
$ adpictl set gain 128
$ adpictl get gain
128
$ adpictl set gain 1
$ adpictl get gain
1
```


#### 電源端子の出力状態「output」
接続先 CH の電源端子の出力状態を設定します。なお、設定するチャンネル番号と出力状態を「on」もしくは「off」をパラメータとして与えます。

```
$ adpictl set output 1 on
$ adpictl get output 1
on
$ adpictl set output 1 off
$ adpictl get output 1
off
$ adpictl set output 2 on
$ adpictl get output 2
on
$ adpictl set output 2 off
$ adpictl get output 2
off
$ adpictl set output 3 on
$ adpictl get output 3
on
$ adpictl set output 3 off
$ adpictl get output 3
off
$ adpictl set output 4 on
$ adpictl get output 4
on
$ adpictl set output 4 off
$ adpictl get output 4
off
```


#### 分解能「scale」 
電圧レンジに対応した分解能を単位「mV」で設定します。設定できる分解能を次に示します。

- 設定できる分解能：`0.000596040 0.000298020 0.000149010 0.000074500 0.000037250 0.000018620 0.000009310 0.000004650`

```
$ adpictl set scale 0.000298020
$ adpictl get scale
0.000298020
$ adpictl set scale 0.000596040
$ adpictl get scale
0.000596040
```


### ヘルプ表示「help」
ADPi Proのヘルプを表示します。 

``` 
$ adpictl help

Usage: adpictl [OPTION] COMMAND ...|

Commands:
    get {frequency|gain|output <CH>|scale|temperature|voltage <CH>}
    set {frequency|gain|output <CH>|scale} <VALUE>
    help                        display help and exit
    version                     display version and exit

Options:
    --config, -c <FILE>         read config from FILE
    --spi, -s <DEVICE_NUMBER>   specify device number by SPI
    --iio, -i <DEVICE_NUMBER>   specify device number by IIO (When using IIO)
``` 

### バージョン表示「version」
ADPi Proのバージョンを表示します。

```
$ adpictl version
adpictl 2.0
```


## OPTION に指定可能な引数

### -c, --config <FILE>
指定したFILE から設定を読み込みます。次の実行例では、defultの設定ファイル「/etc/adpi.conf」を指定して、チャンネル1に接続されているアナログ電圧値を入力します。なお、本OPTION は、現状では adpi-utils 2.0のため、adpi-utils 1.0 の互換性維持のために設けられたOPTIONです。

```
$ adpictl  -c /etc/adpi.conf get voltage 1
299.226384960
```


### -s, --spi <DEVICE_NUMBER>
DEVICE_NUMBER で指定したデバイスを使用します。DEVICE_NUMBER には接続された SPI バスの CS の番号「0」もしくは「1」を指定します。次の実行例では、CS0を指定して、チャンネル2に接続されているアナログ電圧値を入力します。

```
$ adpictl  -s 0 get voltage 2
283.789545000
```

次の実行例では、CS1を指定して、チャンネル1に接続されているアナログ電圧値を入力します。

```
$ adpictl  -s 1 get voltage 1
284.006503560
```

### -i, --iio <DEVICE_NUMBER>
DEVICE_NUMBER で指定されたデバイスを使用します。DEVICE_NUMBER には認識された iio:device の番号を指定します。なお、IIO サブシステムのインタフェースの場合のみ、このOPTIONは指定できます。次の実行例では、認識された iio:device0 を指定して、チャンネル1に接続されているアナログ電圧値を入力します。

```
$ adpictl  -i 0 get voltage 1
278.875195200
```

次の実行例では、認識された iio:device1 を指定して、チャンネル2に接続されているアナログ電圧値を入力します。

```
$  adpictl  -i 1 get voltage 2
278.584327680
```

# 2枚のADPi Proを使用する場合の設定
ADPi Proは、次のように1つのRaspberry Piに対して最大2枚搭載できます。ADPi Proのピンソケット「CN3」を使用してRaspberry Pi にスタックし、もう一枚のADPi Proのピンソケット「CN3」と重ね合わせます。


![cs101.jpg](https://qiita-image-store.s3.amazonaws.com/0/124811/02d5eaa4-f23b-ba0b-c0f2-1d06827ebb05.jpeg)

## ADPi Proのハードウェアの設定
2枚のADPi Proの基板上のジャンパピンとディプスイッチの各設定は、1枚目のADPi Proは購入時のディフォルトの設定とし、2枚目のADPi Proは次の設定を行います。

- JP2：CS1
- JP3：GPIO25 
- DIPSW1：DIP1 ON、DIP2 OFF、 DIP3 ON、DIP4 OFF　（EEPROM：0x56 、GPIO エキスパンダ：0x26）


![cs100.jpg](https://qiita-image-store.s3.amazonaws.com/0/124811/349f99e4-1301-317c-c267-9af5c2acbedb.jpeg)

## ADPi の設定を記述するファイル「/etc/adpi.conf」の変更
ADPi の設定を記述するファイル「/etc/adpi.conf」は、次のように[spi0.1]の使用するデバイスの種類を指定する「device」に、デフォルトで空欄になっているカラムに「adpipro」を設定します。

```
[spi0.0]
device=adpipro
eeprom=0x57
gpio=0x27

[spi0.1]
device=adpipro
eeprom=0x56
gpio=0x26
```

## IIO サブシステムで動作させるために「/boot/config.txt 」への追記
2枚のADPi ProをIIO サブシステムとして動作させる場合、CS0 と CS1 にデバイスを接続する Device Tree Overlay の設定を、次の形式で「/boot/config.txt 」に追記します。なお、 Device Tree Overlay の設定については、「[mechatrax/adpi-firmware](https://github.com/mechatrax/adpi-firmware#%E8%A8%AD%E5%AE%9A)」を参照してください。

```
dtoverlay=adpipro-cs1
dtoverlay=adpipro-cs0
```

「/boot/config.txt」にDevice Tree Overlay の設定がない場合、adpictlコマンドを実行すると、次のようなエラーメッセージが発生します。

```
$ adpictl  -i 1 get voltage 1
find: '/sys/bus/spi/devices//iio:device*': そのようなファイルやディレクトリはありません
Command failure
```

## 【参考】1枚のADPi ProだけでSPIのCS1に接続
1枚のADPi ProだけでSPIのCS1に接続したい場合は、ファイル「/etc/adpi.conf 」を、次のように[spi0.0]の「device」に使用するデバイスが存在しない場合を示す空欄に設定します。

```
[spi0.0]
device=
eeprom=0x57
gpio=0x27

[spi0.1]
device=adpipro
eeprom=0x56
gpio=0x26
```

もし、「device」に空欄を設定しない場合、次のような例外が発生します。

```
TypeError: float() argument must be a string or a number, not 'NoneType'
Command failure
```

# さいごに
ADPi Proで提供されている「adpictlコマンド」は、SPI デバイスとIIO サブシステム共通で使用でき、ソフトウェアを開発する前のADPi Proの動作チェックのために使用でき、またコマンドの構文が分かり易く、与えるパラメータが少なくて使いやすいのでお勧めです。