api_ev3rt_on_athrill - ETrobocon/etrobo GitHub Wiki
ETロボコンシミュレータにおけるEV3RTのAPI対応
Summary
2024/4/1 時点でのETロボコンシミュレータにおけるEV3RTのAPIサポートは以下のようになっています。
mrubyのAPI対応状況はこちらをご確認ください。（この先、軽量mrubyフォーラム管理ドキュメントになります。）
- 外部リンク：TOPPERS「EV3RT C API Reference」
- 外部リンク：TOPPERS「EV3RT C++ API Reference」
| 機能 | サブ機能 | 対応状況 | 備考 |
|---|---|---|---|
| EV3本体機能 | バッテリ | ○ | 常に固定の値が返されます。 |
| 本体ボタン | ○ | シミュレータ上の本体ボタンクリックに対応しています。 | |
| LEDライト | ○ | シミュレータ上の本体のLEDの色が変わります。 | |
| スピーカー | △ | 呼んでも機能せず、ただE_OKを返します。 | |
| ファイルシステム | ○ | 仮想のファイルシステムにアクセスできます。ファイルシステムに関する説明を参照してください。 | |
| LCD | △ | 呼んでも機能せず、ただE_OKを返します。 | |
| シリアル | BT | △ | Bluetooth(R)での通信は対応していませんが、PIPEを使用したやりとりが可能です。詳細はBluetooth通信を参照してください。 |
| モーター | - | ○ * | ev3_motor_rotate()は機能しません（E_OKは返る)。ev3_motor_steer()の挙動も異なるため、使用は推奨されません。 |
| センサ | 超音波センサ | ○ | |
| タッチセンサ | ○ | 通信接続時にSpaceキーがタッチセンサーの代わりとなります。 |
|
| ジャイロセンサ | ○ | シミュレータ（Unity）から得られたパラメータに基づいた値が取得出来ます。 | |
| カラーセンサ | ○ | reflectとget_rgb_rawのみ対応しています。('20/9/23追記) | |
| Clock | - | △ | Clockクラスに仕様上の差異があります。Clockクラスに関する説明を参照してください 。 |
バッテリ
シミュレータ上の走行体は電池の消耗という概念がないため、常に同じ値を返します。
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_battery_current_mA() | ○ | - |
| ev3_battery_voltage_mV() | ○ | - |
本体ボタン
画面で表示されるロボットの本体ボタンをマウスでクリックすることで反応します。
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_button_is_pressed() | ○ | - |
| ev3_button_set_on_clicked() | ○ | - |
LCD
APIとしては存在しますが、機能的には未実装です。常にE_OKを返します。
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_font_get_size() | △ | - |
| ev3_image_free() | △ | - |
| ev3_image_load() | △ | - |
| ev3_lcd_draw_image() | △ | - |
| ev3_lcd_draw_line() | △ | - |
| ev3_lcd_draw_string() | △ | - |
| ev3_lcd_fill_rect() | △ | - |
| ev3_lcd_set_font() | △ | - |
LED
シミュレータ上のロボットの色が変わります。
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_led_set_color() | ○ | - |
スピーカ
APIとしては存在しますが、機能的には未実装です。常にE_OKを返します。
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_speaker_play_file() | △ | - |
| ev3_speaker_play_tone() | △ | - |
| ev3_speaker_set_volume() | △ | - |
| ev3_speaker_stop() | △ | - |
ファイルシステム
EV3のファイルシステムはSDカードへの書き込みを提供しています。 シミュレータ環境ではホスト環境での仮想のファイルシステムを提供しています。
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_bluetooth_is_connected() | △ | 常にtrueを返します。 |
| ev3_memfile_load() | ○ | 仮想ファイルシステムへのアクセスを行います |
| ev3_memfile_free() | ○ | - |
| ev3_sdcard_opendir() | ○ | 仮想ファイルシステムのディレクトリのオープンを行います。 |
| ev3_sdcard_readdir() | ○ | - |
| ev3_sdcard_closedir() | ○ | - |
| ev3_serial_open_file() | △ | Bluetoothの章を参照してください。 |
| ev3_spp_master_connect() | × | 対応していません。 |
| ev3_spp_master_is_connected() | × | 対応していません。 |
| ev3_spp_master_reset() | × | 対応していません。 |
アプリケーションプログラムからfopen("test.txt","rw")とした場合、実機でSDカードのトップディレクトリに書き込まれますが、シミュレータの仮想システムではプログラムを実行したディレクトリに__ev3rtfsというディレクトリを作成し、そのディレクトリをトップディレクトリとしたファイルを作成します。つまり、__ev3rtfs/test.txtというファイルができることになります。
逆に__ev3rtfsの下にファイルを置くことで、EV3RTのプログラムからアクセスさせることもできます。
__ev3rtfsという名前はsdk/common/device_config.txtのDEVICE_CONFIG_VIRTFS_TOPに指定している値で変更できます。ただし、試走会や大会では標準の値（__ev3rtfs）を使用するため、変更しない方が良いでしょう。
libc(実際はnewlib)で提供しているopen,read,write,close、scanf,およびfopen,fread,fwrite,fclose,fprintf,fscanfなども対応しています。
Bluetooth
シミュレータ環境ではBluetooth自体の対応はしていませんが、API上Bluetooth APIを通じてホストコンピュータ側との通信が可能です。
ev3_serial_open_file()でBluetoothを指定した場合、その後のfread(),fwrite()はホスト側への仮想通信路として2つのPIPEを使用します。
__ev3rt_bt_outが出力用、__ev3rt_bt_inが入力用となります。
EV3RTのプログラム側で
FILE *bt = ev3_serial_open_file(EV3_SERIAL_BT);
int c;
while(1) {
c = fgetc(bt);
tslp_tsk(1000000);
fprintf(bt, "Input was=%d\n",c);
}
のようにすると、実行したディレクトリで以下のように__ev3rt_bt_inPIPEに書き込みを行うとfgetc()などで読み込みを行うことができます。
echo "test" > __ev3rt_bt_in
etrobo環境では、以下のようにも呼び出せます。
btecho "test"
逆に、出力に関しては
cat __ev3rt_bt_out
とするとfwrite()などで書き込んだデータが出力できます。
aspを起動した後で別なコマンドウィンドウから
cat __ev3rt_bt_out &
とすると、出力を常に出すことができます。
etrobo環境では、以下のようにも呼び出せます。
btcat
毎回上記のコマンドを実行するのが面倒な場合はプロジェクトのMakefile.inc内のADDITIONAL_PRE_APPLに記述したコマンドを自動的に実行させることができます。
ADDITIONAL_PRE_APPL=cat __ev3rt_bt_out &
と書くと、make sim upなどで実行するとアプリケーションを起動する前にcatコマンドがバックグラウンドで実行されます。
この仕組みはログなどをとるために使用することを想定しています。
大会・試走会では実行委員会側でcatコマンドでのログをとることだけを想定していますので、事前のコマンドを実行することを前提とした走行にならない要注意してください。
モーター
注釈のないものは対応しています。
なお、シミュレータにおいては各モータが以下のポートに割り当てられています。
| ポート | 接続モータ | 備考 |
|---|---|---|
| EV3_PORT_A | アームモーター | - |
| EV3_PORT_B | 右モーター | - |
| EV3_PORT_C | 右モーター | - |
| EV3_PORT_D | しっぽモーター | - |
C API
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_motor_config() | ○ | - |
| ev3_motor_get_counts() | ○ | - |
| ev3_motor_get_power() | ○ | - |
| ev3_motor_get_type() | ○ | ev3_motor_config()で設定したものが取得できます。 |
| ev3_motor_reset_counts() | ○ | - |
| ev3_motor_rotate() | × | 対応していません。使用しないでください。 |
| ev3_motor_set_power() | ○ | - |
| ev3_motor_steer() | △ | 対応はしていますが、実機との実現方法が異なるのと、細かい制御ができないため、使用しない方が良いでしょう。 |
| ev3_motor_stop() | ○ | - |
C++ API
| クラス | 操作 | 対応状況 | 備考 |
|---|---|---|---|
| Motor | Motor() | ○ | - |
| Motor | ~Motor() | ○ | - |
| Motor | getCount() | ○ | - |
| Motor | getPWM() | ○ | - |
| Motor | getPort() | ○ | Motor()で設定したものが取得できます。 |
| Motor | getBrake() | ○ | Motor()で設定したものが取得できます。 |
| Motor | reset() | ○ | - |
| Motor | setPWM() | ○ | - |
| Steering | Steering() | △ | ev3_motor_steer()と同様です。 |
| Steering | setPower() | △ | ev3_motor_steer()と同様です。 |
| Motor | stop() | ○ | - |
| Motor | setBrake() | ○ | - |
センサ
使用する前に設定を行う必要があります（実機と同じ）
なお、シミュレータにおいては各センサーが以下のポートに割り当てられています。
| ポート | 接続センサー | 備考 |
|---|---|---|
| EV3_PORT_1 | タッチセンサー | - |
| EV3_PORT_2 | カラーセンサー | - |
| EV3_PORT_3 | 超音波センサー | - |
| EV3_PORT_4 | ジャイロセンサー | - |
センサの設定
センサの設定には対応しています。
C API
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_sensor_config() | ○ | - |
| ev3_sensor_get_type() | ○ | ev3_sensor_config()で設定したものが取得できます。 |
C++ API
| クラス | 操作 | 対応状況 | 備考 |
|---|---|---|---|
| Sensor | Sensor() | ○ | - |
| Sensor | ~Sensor() | ○ | - |
| Sensor | getPort() | ○ | Sensor()で設定したものが取得できます。 |
カラーセンサ
カラーセンサはシミュレータではUnity上のカメラを使用して取得した画像から返す値を判定しています。そのため、画像切り替えの解像度(fps)が低い場合には精度が低くなります。そのため、ETロボコンの正式な動作環境は60fps固定モード（つまりシミュレータ時間に対して実時間が長くなる）を使用し、大会や試走会も60fps固定で走行させます。fps可変モードではCPUの性能によってカラーセンサの性能が大きく異なる場合がありますので、注意してください。
C API
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_color_sensor_get_ambient() | △ | 取得できる値の保証が困難なため、実験用以外での利用は非推奨です。 |
| ev3_color_sensor_get_color() | △ | 取得できる値の保証が困難なため、実験用以外での利用は非推奨です。色判定は get_rgb_raw を用いて自分で判定してください。 |
| ev3_color_sensor_get_reflect() | ○ | - |
| ev3_color_sensor_get_rgb_raw() | ○ | - |
C++ API
| クラス | 操作 | 対応状況 | 備考 |
|---|---|---|---|
| ColorSensor | ColorSensor() | ○ | - |
| ColorSensor | ~ColorSensor() | ○ | - |
| ColorSensor | getAmbient() | △ | 取得できる値の保証が困難なため、実験用以外での利用は非推奨です。 |
| ColorSensor | getColorNumber() | △ | 取得できる値の保証が困難なため、実験用以外での利用は非推奨です。色判定は getRawColor を用いて自分で判定してください。 |
| ColorSensor | getBrightness() | ○ | - |
| ColorSensor | getRawColor() | ○ | - |
注釈のないものは対応しています。
ジャイロセンサ
ジャイロのAPIには対応しています。
C API
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_gyro_sensor_get_angle() | ○ | - |
| ev3_gyro_sensor_get_rate() | ○ | - |
| ev3_gyro_sensor_reset() | ○ | - |
C++ API
| クラス | 操作 | 対応状況 | 備考 |
|---|---|---|---|
| GyroSensor | GyroSensor() | ○ | - |
| GyroSensor | ~GyroSensor() | ○ | - |
| GyroSensor | getAngle() | ○ | - |
| GyroSensor | getAnglerVelocity() | ○ | - |
| GyroSensor | reset() | ○ | - |
| GyroSensor | setOffset() | ○ | - |
赤外線センサ
ETロボコンでは使用しないため、赤外線センサには対応していません。
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_infrared_sensor_get_distance() | × | 非対応 |
| ev3_infrared_sensor_get_remote() | × | 非対応 |
| ev3_infrared_sensor_seek() | × | 非対応 |
タッチセンサ
タッチセンサに対応しています。キーボードのenterキーを押すことで、反応します。
C API
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_touch_sensor_is_pressed() | ○ | - |
C++ API
| クラス | 操作 | 対応状況 | 備考 |
|---|---|---|---|
| TouchSensor | TouchSensor() | ○ | - |
| TouchSensor | ~TouchSensor() | ○ | - |
| TouchSensor | isPressed() | ○ | - |
超音波センサ
C API
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ev3_ultrasonic_sensor_get_distance() | ○ | - |
| ev3_ultrasonic_sensor_listen() | × | 対応していません。 |
C++ API
| クラス | 操作 | 対応状況 | 備考 |
|---|---|---|---|
| SonarSensor | SonarSensor() | ○ | - |
| SonarSensor | ~SonarSensor() | ○ | - |
| SonarSensor | getDistance() | ○ | - |
| SonarSensor | listen() | × | 対応していません。 |
その他センサ
ETロボコンでは使用しないため、下記のAPIには対応していません。
| 関数 | 対応状況 | 備考 |
|---|---|---|
| ht_nxt_accel_sensor_measure() | × | 非対応 |
| ht_nxt_color_sensor_measure_color() | × | 非対応 |
| ht_nxt_color_sensor_measure_rgb() | × | 非対応 |
| nxt_temp_sensor_measure() | × | 非対応 |
Clockクラス
| 操作 | 対応状況 | 備考 |
|---|---|---|
| reset | ○ | - |
| now | ○ | - |
| wait | △ | シミュレーション時間であることに注意してください |
| sleep | △ | シミュレーション時間であることに注意してください |