橋本商会

Sysexコマンドを実装する為にArduino IDE 1.0.3内のコードを色々読んだ。
日本語どころか英語でもちゃんと解説している文書が見当たらなかったので、忘れる前にメモしておく。

Firmata

Arduinoを操り人形モードにしてPCから指令だして逐次動作させるプロトコルのこと。Midiを元にしている。
http://firmata.org/wiki/V2.1ProtocolDetails

使う分には、だいたいRPCのような物だと思っていて良い。

パソコンとArduinoを連動させるプログラムを作る時、両側のプログラムを書いてシリアル通信で連動させるのは面倒なので、パソコン側プログラムの中にArduinoのプログラムを埋め込めるようにしよう！！ということ。

Arduino本体のコード読むと、Atmel AVRマイコン専用ではなく他社のマイコンでも動かせるように物凄い実装が抽象化されているカッコいいコードな事がわかる。
実際基本的な命令セットのラッパー部分を書き換えればMSP430 LaunchPadもArduino化する。
Firmataも同じように、Arduino専用プロトコルではない。例えばGainerやFunnelでも使っている。

Arduinoを呼び出す側も色々な言語での実装がある。俺が作った物では

• Ruby実装
• Android実装

がある。

Sysex Message

PC-Firmata間で2byte以上のデータをやりとりする時に使う。
Arduino IDE付属のStandardFirmataでは、Arduino→PCへのDIGITAL_MESSAGE, ANALOG_MESSAGE, REPORT_VERSIONの3つで既に使われている。

自作のコマンドをArduinoに実行させるのにも使える。
例えばサーボモーターを角度0〜180まで3秒間かけて動かす処理をする時、普通にFirmata上のservoWrite(サーボ番号, 角度)関数を使うとsleepを駆使して小刻みにPCからArduinoにコマンドを送り続ける。
「n秒かけて角度aからbまで回す」というSysexコマンドを定義すれば、命令は1回で済む。
あとは赤外線リモコンのような38KHzをきっちり送るような処理にも使える。LEDのon/off指令をPCから逐次送信していては間に合わないので、sysexコマンドを自作する。（FlashとArduinoで赤外線リモコン）


[START_SYSEX, コマンド名, 7bitを31個分のデータ, END_SYSEX] を1セットとして送信する。
8bit目が立っているbyteはMidiではコマンドなので、7bitになっている。

http://firmata.org/wiki/V2.1ProtocolDetails#Sysex_Message_Format

/* Generic Sysex Message
* 0 START_SYSEX (0xF0)
* 1 sysex command (0x00-0x7F)
* x between 0 and MAX_DATA_BYTES 7-bit bytes of arbitrary data
* last END_SYSEX (0xF7)
*/

MAX_DATA_BYTESは Arduino.app/Contents/Resources/Java/libraries/Firmata/Firmata.h で定義されている。

デフォルトでコマンド1つ + 7bitデータ31個の合計32個が送れる。

#define MAX_DATA_BYTES 32 // max number of data bytes in non-Sysex messages

コメントにsysex以外のメッセージって書いてあるけど、Firmata.cppのコードを追っていくとsysexのデータを格納する配列サイズはMAX_DATA_BYTESで指定されている。


Firmata.hで定義されているSysexコマンド。0x00-0x0Fはユーザが自分のアプリ内で定義していいらしい。

// extended command set using sysex (0-127/0x00-0x7F)

/* 0x00-0x0F reserved for user-defined commands */

#define SERVO_CONFIG            0x70 // set max angle, minPulse, maxPulse, freq

#define STRING_DATA             0x71 // a string message with 14-bits per char

#define SHIFT_DATA              0x75 // a bitstream to/from a shift register

#define I2C_REQUEST             0x76 // send an I2C read/write request

#define I2C_REPLY               0x77 // a reply to an I2C read request

#define I2C_CONFIG              0x78 // config I2C settings such as delay times and power pins

#define EXTENDED_ANALOG         0x6F // analog write (PWM, Servo, etc) to any pin

#define PIN_STATE_QUERY         0x6D // ask for a pin's current mode and value

#define PIN_STATE_RESPONSE      0x6E // reply with pin's current mode and value

#define CAPABILITY_QUERY        0x6B // ask for supported modes and resolution of all pins

#define CAPABILITY_RESPONSE     0x6C // reply with supported modes and resolution

#define ANALOG_MAPPING_QUERY    0x69 // ask for mapping of analog to pin numbers

#define ANALOG_MAPPING_RESPONSE 0x6A // reply with mapping info

#define REPORT_FIRMWARE         0x79 // report name and version of the firmware

#define SAMPLING_INTERVAL       0x7A // set the poll rate of the main loop

#define SYSEX_NON_REALTIME      0x7E // MIDI Reserved for non-realtime messages

#define SYSEX_REALTIME          0x7F // MIDI Reserved for realtime messages

// these are DEPRECATED to make the naming more consistent

#define FIRMATA_STRING          0x71 // same as STRING_DATA

#define SYSEX_I2C_REQUEST       0x76 // same as I2C_REQUEST

#define SYSEX_I2C_REPLY         0x77 // same as I2C_REPLY

#define SYSEX_SAMPLING_INTERVAL 0x7A // same as SAMPLING_INTERVAL

自作SysexコマンドをArduino側に登録する

登録すると、PC側からSysexコマンド発行すればArduino上で実行できる。

Arduino.app/Contents/Resources/Java/libraries/Firmata/Firmata.cpp にあるattach関数にsysex command (0x00-0x7F)を引数として、コールバックを登録する。

http://firmata.org/wiki/V2.1ProtocolDetails#Sysex_Message_Format を見ると、0x00~0x0Fはユーザが自由に使って良い様に予約されているんだけど、登録しても現在Arduino IDEに付属しているFirmata.cpp内では呼び出されるように実装されてない。

方法は2つで、

1. SysexのSTRING_DATAコマンドが来た時のイベントを登録する
2. Sysexを受信した時の関数を呼び出すように、自分でswitch文に追加する
のどちらか。

1. STRING_DATA (0x71)コマンドが来た時のイベントを登録

STRING_DATAは自作アプリで使える。

STRING_DATA (0x71)はFirmata.cpp内でコールバックとして登録できるようになっているが、Arduino IDE付属のStandardFirmata.inoからは使われていない。

Arduino IDEに入っているスケッチ例のEchoStringで使ってる。

#include <Firmata.h>

byte analogPin;



void stringCallback(char *myString)

{

    Firmata.sendString(myString);

}



void sysexCallback(byte command, byte argc, byte*argv)

{   

    Firmata.sendSysex(command, argc, argv);

}



void setup()

{   

    Firmata.setFirmwareVersion(0, 1);

    Firmata.attach(STRING_DATA, stringCallback);

    Firmata.attach(START_SYSEX, sysexCallback);

    Firmata.begin(57600);

}



void loop()

{   

    while(Firmata.available()) {

        Firmata.processInput();

    }

}

2. Sysexを受信した時のコールバック関数を登録

StandardFirmataを改造して、 void sysexCallback(byte command, byte argc, byte *argv) 関数内のswitch文に書き足すといい。
I2C関係もここで定義されているので破壊しないように注意しつつ追加する。

Arduino IDEに入っているStandardFirmataにLED点滅コマンドを追加してみた。
追加した箇所は差分を見ればわかりやすいと思う。

自作したSysexコマンドを呼び出すPC側のプログラム

試しに、指定したLEDを指定回数、指定間隔(ミリ秒)で点滅させるsysexコマンド(0x01)を作る。


Ruby用Firmataライブラリで、sysexコマンドを送るコード。

require 'rubygems'

require 'arduino_firmata'



arduino = ArduinoFirmata.connect ARGV.shift

puts "firmata version #{arduino.version}"



## regist event

arduino.on :sysex do |command, data|

  puts "command : #{command}"

  puts "data    : #{data.inspect}"

end



## send sysex command

arduino.sysex 0x01, [13, 5, 2]  # pin13, blink 5 times, 200 msec interval

arduino.sysex 0x01, [11, 3, 10]  # pin11, blink 3 times, 1000 msec interval



loop do

  sleep 1

end

Arduino側。
EchoStringのサンプルを改造した。
受け取ったSysexコマンドとデータをそのまま返すようにしてある。

#include <Firmata.h>



void setup()

{

  Firmata.setFirmwareVersion(FIRMATA_MAJOR_VERSION, FIRMATA_MINOR_VERSION);

  Firmata.attach(START_SYSEX, sysexCallback);

  Firmata.begin(57600);

}



void loop()

{

  while(Firmata.available()) {

    Firmata.processInput();

  }

}



void sysexCallback(byte command, byte argc, byte*argv)

{

  switch(command){

  case 0x01: // LED Blink Command

    if(argc < 3) break;

    byte blink_pin;

    byte blink_count;

    int delayTime;

    blink_pin = argv[0];

    blink_count = argv[1];

    delayTime = argv[2] * 100;



    pinMode(blink_pin, OUTPUT);

    byte i;

    for(i = 0; i < blink_count; i++){

      digitalWrite(blink_pin, true);

      delay(delayTime);

      digitalWrite(blink_pin, false);

      delay(delayTime);

    }

    Firmata.sendSysex(command, argc, argv); // callback

    break;

  }

}

StandardFirmataに同様の機能を追加してみた。この方法なら、いつものanalogReadやdigitalWrite機能が使えるままのArduinoに、赤外線学習リモコン機能を追加したりとかできる。
追加した箇所は差分を見るとわかりやすいと思う。


Android版からもRubyと同様にコマンドを送れる。

byte[] data = {11, 3, 10};  // pin11, blink 3 times, 1000 msec interval

arduino.sysex((byte)0x01, data);

Firmata.sendSysex

Arduino側からPCにsysexコマンドを送るFirmata.sendSysex(byte command, byte argc, byte*argv)関数は、内部でsendValueAsTwo7bitBytes(int value)を呼び出している。
sysexで送れるデータは7bitまでなので、8bit以上と7bit以下を2byteに分けて送信するために使われている。
sendSysexに14bitの値を入れれるならいいんだけど、byte配列しか渡せなくて効率が良くないのでFirmata.send関数を直接使いたいがこっちはprivateになっていて使えない。

幸い、PC側はバッファサイズは無限に余裕があるので何byteでも1度に送って問題ない。