seiichi horie / ukifune

API collection of Ukifune. Initial publish. Documents are not ready.

ukifuneはUI基板『浮舟』のAPIモジュールです。 浮舟はNucleo F746ZGに接続して使うUI基板で、以下のような特徴を持っています。

• ピアノ鍵盤を模した13個のタクトスイッチ
• ３個のモード切り替えスイッチ
• １２個のLED
• ２ポートのI2Cを通して使える計8個のボリューム。

以下にukifuneモジュール及び浮舟について解説します。

ハードウェア

浮舟基板は、Nucleo F746ZGのCN12ヘッダーに接続して使うUI基板です。 この写真では中央下の緑の基板が浮舟です。上の白い基板はNucleo F746ZGで、その上には、変換基板桐壺を介してアクアシグナルのUMB-ADAU1361-Aが接続されています。また、浮舟の両側にはやはりアクアシグナルのTPOL-POT4-Aが接続されています。

Nucleo F746ZGのCN12は非常に多くのピンが用意されていますが、そのうち最初の50ピンのみを使っています。使用している機能はGPIO機能のほか、I2C3およびI2C4ポートです。I2C2ポートは、CN11で使えるように手付かずであけてあります。

プッシュボタンはアンチ・チャタリング回路を入れていますが、簡易型であるためあまり効きがよくありません。現時点ではキャパシタの無駄です。追試してみたい方は時定数を大きくするか、いっそアンチ・チャタリング回路をやめてもいいでしょう。

LEDもプッシュボタンも、アクティブHです。すなわち、LEDは論理状態1で点灯し、プッシュボタンを押すと論理状態が1になります。

I2Cポートは基板でプルアップした後、外部に開放しています。これらはアクアシグナルのTOL-POT4-Aに直結できるピン配置になっています。 浮舟基板にはテストポイントが3本出ています。うち1本はGNDで、残りの2本は割り込み処理時間と信号処理時間を測定するためのステータスピンです。

ソフトウェア

ukifuneモジュールは浮舟基板制御用のAPI群です。これらは名前空間ukifuneでラップされており、ukifune.hを読むことで利用できます。 APIの一覧については、このページのAPI Documentationタブを参照してください。APIドキュメントには、LEDおよびプッシュ・ボタン・スイッチをプログラムから参照するための識別子も列挙してあります。

ukifuneモジュールのAPIを使用するためには、事前にukifune::init() APIを一度だけ呼ぶ必要があります。このAPIは内部変数を初期化するほか、雲仙オーディオフレームワークへのポインタを受け取り、フレームワークに対してテストピンを駆動するためのコールバック群を登録します。

ボリュームを使う場合には、周期的に ukifune::tick() を呼んでください。このAPIは呼ばれるたびにI2C経由でADCにアクセスしてアナログ値を読み取り、ukifuneモジュールの内部変数を更新します。呼び出し周期はおおむね50mS以内であれば十分でしょう。周期の精度については適当でかまいません。

プッシュボタンの状態を知りたい場合には、ukifune::get_button_state() を呼び出します。このAPIは3つのビットマスクを返します。

pushing 引数は、前回のAPI呼び出し時からどのボタンが押し込まれたかを返します。言い換えると、前回押されていなかったにもかかわらず、今回のAPI呼び出しで押されていることが検出されたボタンがこの変数から返されます。pushing引数はビットマップであり、ビット位置は enum ukifune::SWITCHの要素の値に対応します。対応するビットが1であるようなスイッチが、押し込まれたスイッチです。

releasing 引数は、前回のAPI呼び出し時からどのボタンが戻されたかを返します。言い換えると、前回押されていたにもかかわらず、今回のAPI呼び出しで押されていないことが検出されたプッシュボタンがこの変数から返されます。releasing引数はビットマップであり、ビット位置は enum ukifune::SWITCHの要素の値に対応します。対応するビットが1であるようなスイッチが、戻されたスイッチです。

pushed 引数は、どのボタンが押されているかを返します。pushed引数はビットマップであり、ビット位置は enum ukifune::SWITCHの要素の値に対応します。対応するビットが1であるようなスイッチが、押されているスイッチです。

ukifune::get_volume()は、ボリュームの状態を返します。引数は0から7の整数で、ボリュームに対応します。返り値の範囲は０から1.0です。

基板設計情報およびパーツリスト

ukifuneの 基板設計情報をアップロードしておきます( 2017/01/28, ver 2 )。

この基板はKiCad 4.0.2 で設計し、出力したgerberデータをスイッチサイエンスの基板製造サービスで製造し、動作を確認しています（写真）。万に一つのことがありますので、基板を外注に出す方は、くれぐれも事前の注意を払ってください。また、この基板は実験用に作成したものであり、民生、産業、医療などの用途に耐えるような設計ではありません。どのような理由であれ、この基板によって発生した問題については責任を取りません。

部品表は以下の通りです。C1の脚の幅にご注意ください。LEDやプッシュボタン・スイッチの色は任意です。なお、U1だけは表面実装部品です。ご注意ください。 以下の部品の他に、Nucleo側のピンヘッダおよび、基板接続用のフラットケーブル（圧接コネクタ付き）が必要です。

Nucleo F746ZGの改造

Nucleo F746ZGは非常に多機能なSoCマイコンを使っています。多くの機能がピンに多重化されているものの、一部は基板外の複数の信号がピンを奪い合う形になっています。これを解決するために、Nucleo F746ZGには多くのショート･ブリッジがあります。

浮舟基板を使うためにはNucleo F746ZGの以下のショート・ブリッジを取り去ってください。

• SB125
• SB132
• SB133
• SB178
• SB181

また、以下のジャンパー･ピンはオープンにしてください。

• JP6
• JP7

以上の改造によって、Nucelo F746ZGのEthernetポートおよび、USB OTGポートが使用できなくなります（ホストと接続しているmbed用USBポートには影響はありません）。

既知の問題

• アンチ･チャタリング回路は見直した方がいいです。現状でチャタリングが残っています。
• C1は他のキャパシタと異なり、2.54mmピッチです。

参考リンク

• 『雲仙』　オーディオ・フレームワーク : フレームワークの全体像の解説。CODEC基板アダプタの設計情報
• skeleton_unzen_nucleo_f746 Nucleo F746ZGおよびUI基板を使う場合のスケルトンプログラム。F746を使う方はここから読み始めると良いでしょう。

diff -r 482c7c12ef76 -r e2a690a654ff ukifune.cpp
--- a/ukifune.cpp	Fri Jan 27 22:13:52 2017 +0000
+++ b/ukifune.cpp	Sat Jan 28 12:50:04 2017 +0000
@@ -132,7 +132,7 @@
     void get_button_state(
             uint32_t & pusshing, 
             uint32_t & releasing, 
-            uint32_t & pushed )
+            uint32_t & holding )
     {
         static int last_button  = 0;
         int current_button = 0;
@@ -148,7 +148,7 @@
         }
         
             // return pushed button
-        pushed = current_button; 
+        holding = current_button; 
         
             // buttons which are pushed from last state.
         pusshing =  ( last_button ^ current_button ) & current_button;

diff -r 482c7c12ef76 -r e2a690a654ff ukifune.h
--- a/ukifune.h	Fri Jan 27 22:13:52 2017 +0000
+++ b/ukifune.h	Sat Jan 28 12:50:04 2017 +0000
@@ -68,15 +68,15 @@
         /**
         * \breif get the state of the button switches. 
         * \param pushing   [out] Bit map of the switch which is changing state from released to pushed. "1" is pushed. 
-        * \param releasing  [out] Bit map of the switch which is changing state from pushed to released. "1" is releasing.
-        * \param pushed   [out] Bit map of the switch which is pushed. "1" is pushed.
+        * \param releasing [out] Bit map of the switch which is changing state from pushed to released. "1" is releasing.
+        * \param holding   [out] Bit map of the switch which is kept pushed. "1" is holding.
         * \details
         * The bit position in the bit map are represented by enum SWITCH.
         */
     extern void get_button_state(
                         uint32_t & pushing, 
                         uint32_t & releasing, 
-                        uint32_t & pushed 
+                        uint32_t & holding 
                         );
     
         /**