ライブラリ解説
● はじめに
JR PROPO製XBusサーボモータ(以下、XBusサーボ)にご興味をお持ちいただき、ありがとうございます。XBusServoライブラリ解説(以下、本ドキュメント)は、XBusサーボをマイコンボード「Arduino」(以下、Arduino)からお使いいただく時のためのXBusServoライブラリ(以下本ライブラリ)について解説しています。
XBusサーボが採用している1線半二重の通信を行うのに必要な回路図についても、簡単に解説しておりますので、参考になさって頂ければ幸いです。以下の章に記載しました仕様は、まだまだ拡張可能な要素を残しております。もし何かご要望等がございましたら、後述の専用窓口までご相談いただければと思います。
ArduinoにXBusサーボを接続して、様々な作品が生み出されていくことを願っております。
● 注意事項
- 本ドキュメントは、XBusサーボをArduinoに接続して使うためのライブラリに関する仕様概略です。このドキュメントに掲載されていない部分については、別ドキュメントの「XBusサーボ仕様概略」をご参照ください。
- 本ドキュメントはArduinoに対応するものではありますが、全てのArduinoでの動作を保障するものではありません。現時点においては、Arduino UNOでの動作を前提に記述されています。互換機等、他の環境での動作については確認しておりませんので、ご注意ください。
- 本ドキュメントや本ライブラリは、製品改良等及びドキュメント改良等のため予告なく変更されることがあります。
- 本ドキュメントや本ライブラリは、状況に応じて非公開になる場合があります。その際、下記お問い合わせ窓口も閉鎖になる場合があります。
- 本ドキュメントや本ライブラリの無断転載は、最新情報更新の妨げになる場合が多いですのでお控えください。但し、本ドキュメントを基にした解説等の公開や、その際に必要な正しい引用については無論問題ございません。むしろ、歓迎いたします。もしよろしければ、その際は参照用として弊社webページへのリンク等を掲示していただければ幸いです。
- 本ドキュメントや本ライブラリに関連するトラブル等については、弊社は一切の責任を負わないものとします。なお、弊社製品について修理等が必要な場合には、弊社サービス部宛に通常の修理品としてご依頼頂ければ随時対応いたします。
- 本ドキュメントや本ライブラリに関するお問い合わせは、下記の専用メールアドレス宛のみとします。なお弊社サービス部は、本ドキュメントや本ライブラリに関しては一切お答えできません。常にXBusサーボ担当者が応対にあたります。また、担当者不在等により頂いたメールの返答には2週間程度かかる場合があり、全てのお問い合わせにお答えできるとは限らないものとします。
● ハードウエアについて
< 通常仕様 >
XBusサーボをArduinoに接続する場合、Arduinoの信号線は基本的に5Vでありかつ通常の2線双方向シリアル信号ですので、これを3.3Vの1線双方向シリアル信号に変換する必要があります。
以下の回路はその概略です。
やっていることとしては、
- TXに3ステートバッファを入れ、受信時にTXのラインをカットする。
- 3.3V駆動のバッファ(上の例では74125と表記)を使い、レベル変換を行う。
- 保護抵抗を入れ、回路を保護する。
といった辺りです。回路図中の74125は、実際には最近販売されているタイプで構いませんが、信号レベルがTTLであること、電源電圧が3.3Vであること、入出力ともに5Vトレラントであることが条件です。
出力側が5Vトレラントでない場合、Arduino基板のRxのプルアップがRxバッファの出力側から回り込み、3.3V電源を上昇させてしまいますのでご注意ください。その場合は、Rxバッファのみ5V電源にすれば解決する場合がありますが、入力レベルに注意が必要です。
Pin2が回路図上指定されていますが、これは固定ではなく任意のデジタルピン、アナログピンを設定できます。ライブラリの初期化時に、何番のピンを使うのかを指定しています。
10KΩでプルアップしていますが、これは受信に切り替えた時になんらかの理由で一時的にバスのレベルが下がるのを防止するために入れています。XBusサーボからの情報を受信する際、一時的に双方が受信する状態になる場合があり、このときバスのレベルが下がってしまうと、信号が開始されたと勘違いをする場合があるためです。
なお、このプルアップの値は100KΩまでの間で調整するのが望ましいです。特に複数のXBusサーボを設置する場合は、もう少し大きな値にしておくことをお勧めします。
< TX Only 仕様 >
XBusサーボからの情報を一切受け取らない場合、TXのみの接続で動かすことができます。使用部品は通常仕様とあまり変わりませんが、RX側の回路や切り替え信号が不要になります。
ただし、この場合以下の制限があります。
- 一切XBusサーボの情報を受け取れない。
- ID設定を含む各種設定は、その都度個別に当該XBusサーボのみを接続して行う。
気軽にXBusサーボを使う場合は、こちらの方が便利かもしれません。
通常仕様に合わせて10KΩでプルアップしていますが、こちらはあってもなくても特に大きな問題はありません。
なお、このプルアップを設置する場合は100KΩまでの間で調整するのが望ましいです。特に複数のXBusサーボを設置する場合は、もう少し大きな値にしておくことをお勧めします。
< 3.3V仕様のArduinoについて >
一部のArduino(及び互換機)には、もともと信号が3.3Vで出力されているものがあります。この場合、レベル変換は不要かと思いますが、通常仕様の場合はTXを遮断するバッファが必要になります。また、マイコンボード自体の出力が弱い(出力インピーダンスが高い)場合、最悪は信号が鈍る可能性もありますので、安全のためにも5V仕様と同様、バッファを入れておくことをお勧めします。
● ソフトウエアについて
【 概略1】初期化について
本ライブラリは、XBusサーボのパケットプロトコルを内包しています。ですので、ArduinoユーザーはAPIを呼ぶだけで、細かい初期設定抜きにXBusサーボ相手にコマンドを送受信できるようになっています。内部的にはCRC計算等の面倒な処理もありますが、本ライブラリを使えばそういったことに煩わされる心配はありません。
メモリの少ないArduinoでの使用を踏まえ、本ライブラリ初期化時に使用するXBusサーボの最大数を設定することで、必要最小限のメモリをバッファとして割り当てるようにしています。XBusサーボの仕様上の最大数である50個分を確保すると、500バイト強のメモリが割り当てられてしまいますので、ご注意ください。
本ライブラリ初期化時には、同時にTXを制御する信号線を割り当てます。前述の回路図ではPin2に割り当てていますが、デジタル信号が出る端子であれば、どこでも構いません。また、この割り当て引数にマイナス1を与えると、TXOnly仕様として動作します。
割り当てたバッファには、使用するXBusサーボを登録していきます。もちろん、登録できる最大数は、本ライブラリ初期化時に指定した数までです。登録するときは、登録するXBusサーボの初期位置とチャンネルIDを任意に設定できます。
登録するチャンネルIDは一連でなくても構いません。ですので、たとえば「0x05, 0x02, 0x07」の三つを使うといった設定も可能です。使用途中での追加登録、削除も問題ありませんが、その際は位置情報の送信メソッド呼び出しとタイミングが被らないようにだけ注意してください。被ってもトラブルにはなりませんが、登録、削除中はデータが送信されません。
なお、登録する必要があるのは位置の指示を行う場合だけです。ですので、たとえばチャンネルID設定機を製作する等設定を行うだけの場合は、登録を行う必要はありません。その場合、XBusサーボの最大数にも0を指定して構いません。
【 概略2】操作について
通常、XBusサーボは位置情報を受け続けないと脱力するように設定されています。そのため、Arduinoでどんな操作が行われていても位置を維持するために、タイマを用いて位置情報送信のメソッドを常に呼ぶようにしてください。サンプルコードでは、そのやり方も解説しています。
XBusサーボのストップモードをオンにすると、最後に受け付けた位置情報の位置で維持されます。脱力させることが不要で、特定のタイミングでのみ動作させたい場合は、事前に各XBusサーボのストップモードをオンにしてください。必要なタイミングで位置情報送信のメソッドを呼べば、送信したタイミングでその通りに動作します。初心者には、こちらの方が使いやすいかもしれません。
位置の指示は16bitで行います。この値は、従来のPWM信号の概念を踏襲しており、以下のような値で指示します。XBusサーボは概ね850-2150uSecの範囲で動作するようになっています。それ以外の範囲での角度指定については、脱力します。
0x0000 | 800 uSec | |
0x1249 | 900 uSec | -60度、または-90度 |
0x7FFF | 1500 uSec | 0度 |
0xEDB6 | 2100 uSec | +60度、または+90度 |
0xFFFF | 2200 uSec |
ただし、後述のリミット値が設定されている場合、その値よりも外側の指示についてはリミット値でクリップされるため、設定によっては脱力せず、リミット位置で停止します。現時点では、リミット値が工場出荷時に800-2200で設定されているため、リミット値は無効になっています。
XBusサーボの最大角は通常120度ですが、設定により180度まで広げることができます。用途に応じ、設定のコマンドを送信して切り替えて使うのがお勧めです。この場合、位置の指示は同じく900-2100で180度動作するようになっています。
< コンストラクタ >
XBusServo myXBusServo(kDirPinNum, kMaxServoNum);
kDirPinNum | 通常仕様で接続する場合の、TX切り替え端子を指し示します。前述の回路図では、2になります。この値にマイナス1を指定すると、TXOnlyモードとして動作します。シールドの回路に合わせて選択してください。 |
kMaxServoNum | 接続するXBusサーボの最大数を指示します。 |
XBusサーボを使用する場合、最初に必ずこの宣言が必要になります。もちろん、名称は「myXBusServo」でなくても構いません。
注意:もしサブIDを使う場合、同一サーボID分は単一のXBusサーボとしてカウントしてください。サブIDに関しての詳しい情報は、「XBusサーボ仕様概略」をご覧ください。
< 使用開始・終了関係のメソッド >
void begin (void);
パラメータ | なし |
戻り値 | なし |
XBusサーボを使用する場合、最初に必ずこのメソッドを呼んでください。これ以降、シリアルポートは本ライブラリが占有します。通常はsetupメソッドの内部で呼びます。
void end (void);
パラメータ | なし |
戻り値 | なし |
XBusサーボの使用を終了する場合、最後に必ずこのメソッドを呼んでください。これ以降、シリアルポートは開放されます。
< XBusサーボ登録・角度指示関係のメソッド >
XBusError addServo(char channelID, unsigned int initValue);
channel ID | 登録するXBusサーボのチャンネルID |
initValue | 登録するXBusサーボの初期角度。 |
戻り値 | エラーコード |
XBusサーボを登録します。kMaxServoNum の個数分呼ぶことができます。
XBusError removeServo(char channelID);
channel ID | 削除するXBusサーボのチャンネルID |
戻り値 | エラーコード |
登録されたXBusサーボを削除します。
XBusError setServo(char channelID, unsigned int value);
channel ID | 位置指示するXBusサーボのチャンネルID |
Value | 位置指示値 |
戻り値 | エラーコード |
XBusサーボへ位置指示をします。ただし、この段階ではまだXBusサーボには送信されていません。本ライブラリ内部のバッファに蓄積されただけです。
void sendChannelDataPacket(void);
パラメータ | なし |
戻り値 | なし |
XBusサーボへ位置指示のためのデータを送信します。この時点で、登録されている全てのXBusサーボへの位置指示が一括して行われます。
< 通常仕様時のコマンド関係のメソッド >
XBusError setChannelID (char Äb0oldChannelID, char newChannelID);
oldChannelID | チャンネルIDを変更したいXBusサーボのチャンネルID |
newChannelID | 新しいチャンネルID |
戻り値 | エラーコード |
XBusサーボのチャンネルIDを変更します。oldChannelID が設定されているXBusサーボのチャンネルIDを newChannelID に変更します。oldChannelID にゼロを指定した場合、接続されている全てのXBusサーボが newChannelID で指示される同一のチャンネルIDに設定されます。
XBusError setCommand(char channelID, char order, int* value);
channelID | 設定するXBusサーボのチャンネルID |
order | 設定項目 |
value | 指示内容(指示後は設定値が戻ります) |
戻り値 | エラーコード |
XBusサーボの設定を変更します。設定項目や設定値の解説は、下記の表ををご覧ください。
XBusError getCommand(char channelID, char order, int* value);
channelID | 取得するXBusサーボのチャンネルID |
order | 設定項目 |
value | 設定値 |
戻り値 | エラーコード |
XBusサーボの設定値を取得します。設定項目や取得値の解説は、下記の表ををご覧ください。
< 通常仕様時のコマンド関係のメソッド >
XBusError setChannelID (char oldChannelID, char newChannelID);
oldChannelID | チャンネルIDを変更したいXBusサーボのチャンネルID |
newChannelID | 新しいチャンネルID |
戻り値 | エラーコード |
XBusサーボのチャンネルIDを変更します。oldChannelID が設定されているXBusサーボのチャンネルIDを newChannelID に変更します。oldChannelID にゼロを指定した場合、接続されている全てのXBusサーボが newChannelID で指示される同一のチャンネルIDに設定されます。
XBusError setCommand(char channelID, char order, int* value);
channelID | 設定するXBusサーボのチャンネルID |
order | 設定項目 |
value | 指示内容(指示後は設定値が戻ります) |
戻り値 | エラーコード |
XBusサーボの設定を変更します。設定項目や設定値の解説は、下記の表ををご覧ください。
XBusError getCommand(char channelID, char order, int* value);
channelID | 取得するXBusサーボのチャンネルID |
order | 設定項目 |
value | 設定値 |
戻り値 | エラーコード |
Busサーボの設定値を取得します。設定項目や取得値の解説は、下記の表ををご覧ください。
< TXOnly仕様時のコマンド関係のメソッド >
XBusError setChannelID (char newChannelID);
newChannelID | 新しいチャンネルID |
戻り値 | エラーコード |
現在接続されている全てのXBusサーボのチャンネルIDを、newChannelID に変更します。
XBusError setCommand(char order, int* value);
order | 設定項目 |
value | 設定値(指示後は設定値が戻ります) |
戻り値 | エラーコード |
現在接続されている全てのXBusサーボの設定を変更します。設定項目や設定値の解説は、下記の表をご覧ください。
Order | Name | 意 味 | 初期値 | 備 考 |
0x04 | Version | ファームウエアバージョン | 機種毎 | get only |
0x05 | Product | 機種番号(別表2参照) | 機種毎 | get only |
0x07 | Parameter Reset | 下記別表1のIndexで指定したパラメータを初期値に戻す。 | —– | get only |
0x08 | Parameter Write | 下記別表1のIndexで指定したパラメータをROM領域へ書き込む。 | —– | get only |
0x10 | Reverse | 0x0000 通常動作 0x0001 左右反転動作 | 0x0000 | |
0x11 | Neutral | ニュートラル位置(1500uSec)に対するオフセットを指定する。 ±600の範囲で指定できる。主に複数XBusサーボの同期連動時補正に使用する。 | 0 | |
0x12 | Travel High | ニュートラル位置(1500uSec)よりも上の領域において、角度指示を拡大する。 通常128、最大192まで指定できる。主に複数XBusサーボの同期連動時補正に使用する。 | 128 | |
0x13 | Travel Low | ニュートラル位置(1500uSec)よりも下の領域において、角度指示を拡大する。 通常128、最大192まで指定できる。主に複数XBusサーボの同期連動時補正に使用する。 | 128 | |
0x14 | Limit High | 角度指示できる最大値。Limit Low未満には設定できない。 無理に設定しても、自動的にLimit Lowに修正される。 | 0xFFFF | |
0x15 | Limit Low | 角度指示できる最小値。Limit Highより大きくは設定できない。 無理に設定しても、自動的にLimit Highに修正される。 | 0x0000 | |
0x16 | P Gain | XBusサーボが持つPゲインに対する増減値。 ±50の範囲で指定できる。 | 0 | |
0x17 | I Gain | XBusサーボが持つIゲインに対する増減値。 ±50の範囲で指定できる。 | 0 | |
0x18 | D Gain | XBusサーボが持つDゲインに対する増減値。 ±50の範囲で指定できる。 | 0 | |
0x19 | Dead Band | XBusサーボが持つデッドバンドに対する増減値。 ±10の範囲で指定できる。 | 0 | |
0x1A | Boost | XBusサーボが持つブースト値に対する増減値。 ±999の範囲で指定できる。 | 0 | |
0x1B | Alarm Level | XBusサーボからアラームが発せられるパワー閾値。 0-100%で指定できる。アラームが発せられると、モータ音が変化する。 | 機種毎 | |
0x1C | Alarm Delay | XBusサーボからアラームが発せられるまでの遅延時間を指定できる。 この時間が経過しない範囲で閾値から下がれば、警告されない。 0-5000mSecまで指定できる。 | 機種毎 | |
0x1D | Angle | 0x00 通常動作(最大角120度) 0x01 最大角180度(一部の機種では、180度に到達しない場合がある) | 機種毎 | |
0x1E | Slow Start | 0x00 起動後、すぐに通常動作する。 0x01 起動時、最初に取り込んだ指示位置までゆっくり移動する。ただし、移動中に指示位置が変化した場合、その時点から通常動作に戻る。 | 機種毎 | |
0x1F | Stop Mode | 0x00 通常動作(角度指示が途絶えると1秒前後で脱力する) 0x01 ホールド動作(角度指示が途絶えると直前の位置を維持する) | 0x00 | |
0x20 | Current Position | 現在の出力軸の位置を返す。静止していても、指示位置と一致しているとは限らないので注意すること。 | —– | get only |
0x21 | Current Power | 現在モータへ掛けているパワーを返す。0-100%の値を示す。 | —– | get only |
0x22 | Speed Limit | 0 通常動作 1-30 速度制限モード(1が最も遅い) | 機種毎 | |
0x23 | Max Integer | Iゲインの積分値リミッタに対する増減値。±999の範囲で指定できる。 | 0 |
【 別表1 】 Parameter Reset、Parameter WriteにおけるIndex
Index | 名 前 | 適 用 | 備 考 |
0x0001 | All Data with ID | reset only | CH-IDを0x00にする必要がある。ROM領域へ自動で記録される。 リセットに成功すると、チャンネルIDは0x01になる。 |
0x0002 | All Data without ID | reset only | |
0x0003 | Servo ID | reset only | CH-IDを0x00にする必要がある。ROM領域へ自動で記録される。 リセットに成功すると、チャンネルIDは0x01になる。 |
0x0004 | Reverse | both | |
0x0005 | Neutral | both | |
0x0006 | Travel High | both | |
0x0007 | Travel Low | both | |
0x0008 | Limit High | both | |
0x0009 | Limit Low | both | |
0x000A | P Gain | both | |
0x000B | I Gain | both | |
0x000C | D gain | both | |
0x000D | Dead Band | both | |
0x000E | Boost | both | |
0x000F | Alarm Level | both | |
0x0010 | Alarm Delay | both | |
0x0011 | Angle | both | |
0x0012 | Slow Start | both | |
0x0013 | Stop Mode | both | |
0x0014 | Speed Limit | both | |
0x0015 | Max Integer | both |
別表2 Productにおける[ 応答値 / サーボ機種名 ]
■ JR PROPO / DFA model
[0x021A/E555XBUS] [0x02A3/S8477BL] [0x0297/S8911BL-2K] [0x0295/S8955SS-2K] [0x029C/S8944] [0x0293/S8912SHV-2K] [0x0299/S8914SHV-2K] [0x292/S3911-2K] [0x028A/S3411-2K] [0x029D/S3415-2K] [0x029B/S1855-2K]■ 旧JR PROPO model
[0x0200/NX8921] [0x0201/NX3421] [0x0202/NX588] [0x0203/NX8925] [0x0204/NX3425] [0x0205/NX6421] [0x0206/NXR89] [0x0207/NXR34] [0x0208/NXB8921] [0x0209/NXB8925] [0x020A/NXB89G] [0x020B/NX8931] [0x020C/NX8935] [0x020E/NX35G] [0x020F/NX396] [0x0210/NX319] [0x0211/NX189]< エラーコード解説 >
kXBusError_NoError | エラーはありません。 |
kXBusError_CRCError | CRCに問題があります。多くの場合、これは受信エラーです。 |
kXBusError_ServoNumOverflow | これ以上、XBuxサーボを登録できません。 |
kXBusError_ServoNumIsZero | これ以上、XBusサーボを削除できません。 |
kXBusError_AddWithSameID | 新たに登録しようとしたのと同じチャンネルIDのXBusサーボが既に登録されています。 |
kXBusError_IDNotFound | そのチャンネルIDは見つかりません。 |
kXBusError_Unsupported | その指示はサポートされていません。 |
kXBusError_OnlyForTxOnlyMode | そのコマンドはTxOnlyモードでしか使えません。 |
kXBusError_OnlyForNormalMode | そのコマンドは通常仕様でしか使えません。 |
kXBusError_MemoryFull | メモリが不足しています。 |
kXBusError_TimeOut | データ読み出し中にタイムアウトしました。 |
● スペシャルサンプルコード“XBusServoChecker”について
< 概略 >
本サンプルコードは、XBusサーボのパラメータを変更できる設定器をArduinoを用いて実装する場合のサンプルです。なお、このコードは実際に業務で使用しているものをそのまま添付しておりますが、作業用ですので、あまり細かい部分までは配慮がなされていない事をご了承ください。
< ハードウェア構成 >
ざっとした回路図を後に記載しました。基本的に以下の部品を実装しています。コードに合わせて実装するか、自身の思う配置で実装してコードを修正するかはお任せします。なお、全ての部品が秋葉原の電子部品店等で購入可能なものになっていますので、入手は容易かと思います。参考までに、秋月電子通商さんでの番号も付記します。回路図中には描いていませんが、もちろん双方向用のバッファの電源はどちらも3.3Vにしてください。
- 前述のXBus双方向通信用バッファ回路(I-06481、P-04800等)
- バッファ回路用3.3V電源回路(I-00538、P-06165、P-05002等)
- タクトスイッチ4つ(P-03646、P-03649、P-03651、P-03650等)
- ロータリーエンコーダ1つ(P-06357、P-07240、P-00997等)
- I2C接続小型LCD1つ(P-06669、P-06794、K-06795等)
- 基板、配線関係(P-07555、C-00167、C-04397等)
< ソフトウェア構成 >
基本的な使い方としては、上下左右のボタンでカーソルの位置を移動させ、その項目に対してロータリーエンコーダーを回して変化させるという形になっています。
なお、同時にリンクするLCDのライブラリによっては、カーソル移動の指示を出してもカーソルが表示されない場合がありますので、適宜ライブラリの変更をお願いします。
< 注 意 >
Arduino側の3.3V電源は容量が小さいのか、バッファ回路を接続するとうまく動作しないことがありましたので、別途電源を確保しています。
サーボ用の電源を一旦シールド基板へ接続し、ArduinoのVinへ供給することでArduino基板を動作させる方式で実装しています。本来はイリーガルだったかと思いますが、現状UNOでは問題は発生していません。気になる方は、別途電源を直接Arduino側へ供給すればよろしいかと思います。なお、Arduino側電源からサーボへの電源を確保すると、最悪の場合基板が焼き切れるかもしれませんので、ご注意ください。
Copyright JRPROPO all rights reserved.
【XBUSサーボプロトコル仕様概要】は下のバナーをクリック