Intel EdisonのMCU SDKの日本語意訳(7/9):MCU SDKとAPIの使用: MCU API

はじめに

このメモはIntel Edison Compute Module用のMCU SDKの公式ページ群を“さかきけい”が読んで解釈した内容を元に日本語で書き起こしたものです。このメモで雰囲気を感じ取ったうえで原文をご参照いただければと思います。なお、リンク先がないものやリンク先が英語表記になっているものは現状ではまだメモを作成していないものです。

お願い

もしもIntelの関係者で、私がこの日本語ドキュメントを公開することが何らかのライセンスや法的問題があるとお考えであるならば、メールにてご連絡をいただければと思います。その際は、私がメールの送付主がIntel関係者であることを認識できるようにIntel社内からメールを送信し、所属・肩書き等を添えてください。

著作権等

英語版の資料をベースにしているこの日本語ドキュメントはIntelの著作権が及ぶ範囲内にあります。その上で、この日本語ドキュメントには“さかきけい”の著作権が発生しています。“さかきけい”はすべての著作権法上の権利を留保します(詳しくは「ご利用上の注意とお願い」を参照ください)。

免責の表明

この日本語ドキュメントはIntel Corporationが公開しているIntel Edison Compute Module用のMCU SDKの公式ページ群の情報を元に、“さかきけい”の理解で作成したものです。このためIntel Corporationには何らこの日本語ドキュメントに対する責任はありませんので、この日本語ドキュメントに関連する問い合わせをIntelに対して行うことを禁止します。

また、この日本語ドキュメントを作成した“さかきけい”も何ら責任を負いません。この日本語ドキュメントの内容は、利用者自身の責任においてのみ使用することができます。

使用上の注意

  • 複数の英単語によって構成される語は、単語間に「・」を入れて表現しています。例:ルート・ファイル・システム※1
  • 原則として単語末の長音記号「ー」は省略しない方針で編集しています。例:プロセッサー※2
  • 気づいたTypoや編集ミスなどは明確であると考えられる場合に若干修正しています。
  • 日本語での記述におかしいと思われる個所がある場合には原書をあたってください。
  • 技術的などの理由で記載内容にわからない事項がある場合には別途調べてください(“さかきけい”に質問のメールを送るのはご遠慮ください※3)。
  • 明らかな誤訳がある場合には具体的なご指摘をメールでお知らせいただけると助かります。
  • 記述内容に誤りがある場合にもお知らせいただけると嬉しく思います。ただし、原書も間違っている場合には特に日本語ドキュメントを修正することはせずに、訳注を追加するだけとするかもしれません。
  • 前述の内容と被りますが、“さかきけい”は何ら責任や義務を負うものではありません。

文書についてのご指摘をいただける方へのお願い

  • なるべく平坦でかつ理解しやすい程度に周辺情報を含む、日本語でのご指摘をお願いします。特に今回は“さかきけい”の理解の範疇を超えたハードウェアに関する部分のため、従来より多くの問題が存在し、それを理解するための周辺情報も多く必要であることが見込まれます。
  • “さかきけい”の主観において、いただいた情報の適用を行わないことがあることをあらかじめご理解ください。
  • ご連絡をいただける際には、以下の優先度でお願いします:
    1. “さかきけい”へのメール
    2. Facebook経由でのコンタクト
    3. このメモへのコメント

    ただし、このメモへのコメントの場合、大量のスパム・コメントに埋もれて反応が遅くなったり気づかない可能性があります。できる限りメールかFacebookでお願いします。


MCU API

MCU APUは使用できる以下のインターフェースを提供します:

  • GPIO、I2C、およびUARTを含むMCUに接続する周辺機器の制御。
  • ホスト・システムとの通信。
  • 補助的な処理を実行する機能。

さらなるMCU APIの情報については、MCU_SDK_HOME/docs/api_doc/html/index.htmlを参照ください。なお、MCU_SDK_HOMEにはMCU SDKをインストールしたフォルダーが入ります。

注記: MCU APIは浮動小数点をサポートしません。それぞれの機能の詳細な定義についてはmcu_api.hを参照ください。

ハードウェア・リソースにアクセスするAPI

GPIOにアクセスするためのAPI

gpio_setup

1つのGPIOポートを入力または出力モードに設定します。同じGPIOポートのために異なるパラメーターでこのAPIを呼び出して構いません。例えば、入力なっているGPIOを以降は出力と設定することができます。

void gpio_setup(int gpio, int direction)

…これらは:

  • gpio: GPIOポート番号
  • direction: 0 = 入力, 1 = 出力

gpio_register_interrupt

1つのGPIOポートに対する割り込みハンドラーを登録します。

int gpio_register_interrupt(int gpio, int mode, irq_handler_t isr);

…これらは:

  • gpio: GPIOポート番号
  • mode: 0 = 立ち下がりエッジ割り込み, 1 = 立ち上がりエッジ割り込み
  • isr: 割り込みハンドラー関数
  • 返り値: 0ならば成功

gpio_read

1つのGPIOから値を読み出します。

int gpio_read(int gpio)

…これらは:

  • gpio: GPIOポート番号
  • 返り値: 0 = 低電圧, 1 = 高電圧

gpio_write

1つのGPIOポートへ値の書き込みをします。

void gpio_write(int gpio, int value)

…これらは:

  • gpio: GPIOポート番号
  • value: 0 = Low, 1 = High

I2CにアクセスするためのAPI

MCUはI2C6バスに多重化されるI2C8バスに接続するI2Cデバイスにアクセスすることができます。MCU APIを通してI2Cデバイスからの生データを簡単に得ることができます。MCUはI2C-8を使用しますが、Intel® Atom™プロセッサーはI2C-6を使用します。デフォルトでは、(例えばIntel® Atom™チップのための) 多重化されたI2C-6が選択されています。※4詳細に関してはMCUからデバッグ・メッセージを取得するを参照ください。

i2c_read

I2Cデバイスのレジスターから値を読み出します。

int i2c_read(int address, int reg, unsigned char *buf, int length)

…これらは:

  • address: I2Cデバイスのアドレス
  • reg: レジスターのアドレス
  • buf: 値を出力するために事前に確保したバッファー
  • length: バッファーの長さ
  • 返り値: 成功すれば0

注記: Viperではmallocを使用しないことを強く勧めます。MCUアプリケーション開発のために、静的なバッファーのサポートをするのみです。

i2c_write

I2Cデバイスのレジスターへ値を書き込みます。

int i2c_write(int address, int reg, unsigned char *buf, int length)

…これらは:

  • address: I2Cデバイスのアドレス
  • reg: レジスターのアドレス
  • buf: 出力する値を格納したバッファー
  • length: バッファーの長さ
  • 返り値: 成功すれば0

注記: MCUアプリケーションがアクセスできるのはI2C8のみです。

UARTへアクセスるためのAPI

MCUはUART2と同様にUART1へアクセスすることができます。また、UART2はLinuxカーネル・コンソールとして使用することができます。UART2(ttyMFD2)はホストとMCUの両者によって共有されます。Linux側からsystemctl stopserial-getty@ttyMFD2.serviceと実行することによって、ホスト側からの出力を無効にすることができます。

uart_setup

UARTデバイスのボー・レートを設定します。※5

int uart_setup(unsigned char port, int baudrate)

…これらは:

  • port: UARTポート番号(1または2
  • baudrate: UARTのボー・レート
  • 返り値: 成功すれば0

サポートするボー・レートの値は以下の通りです:

  • 115,200
  • 57,600
  • 38,400
  • 28,800
  • 19,200
  • 14,400
  • 9600
  • 7200
  • 4800

他のUARTパラメーターは以下の通りで、これらを変更することはできません。

  • 8ビットのデータ
  • 1ビットのストップ・ビット
  • パリティーなし
  • フロー制御なしl

uart_read

UARTデバイスから読み出しを行います。

int uart_read(unsigned char port, unsigned char *buf, int length)

…これらは:

  • port: UARTポート番号(1または2、ただし現在のところ2のみをサポートしています)
  • buf: 読み出しを行うバッファー
  • length: バッファーの長さ
  • 返り値: 成功すれば0

uart_write

UARTデバイスへ書き込みを行います。

int uart_write(unsigned char port, unsigned char *buf, int length)

…これらは:

  • port: UARTポート番号(1または2、ただし現在のところ2のみをサポートしています)
  • buf: 書き込みを行うバッファー
  • length: バッファーの長さ
  • 返り値: 成功すれば0

ホストと通信するためのAPI

host_send

ホスト(/dev/ttymcu0)へMCUからの生データを送信します。

int host_send(unsigned char *buf, int length)

…これらは:

  • buf: 送信するためのデータを含むバッファー
  • length: バッファーの長さ
  • 返り値: 成功すれば0、失敗した場合にはエラー・コードを返します。

host_receive

ホスト(/dev/ttymcu0)からのMCUへの生データを受信します。このAPIは同期を行いながらバッファーからのデータを取得します。バッファーのサイズは制限されています。データがバッファーのサイズの制限を超える場合には、新しいデータは古いデータを上書きします。

int host_receive(unsigned char *buf, int length)

…これらは:

  • buf: 受信のためのバッファー
  • length: バッファーの長さ
  • 返り値: 受信したデータのサイズ

PWMの制御をするためのAPI

MCUはPWM0からPWM3までのすべてのポートにアクセスすることができます。PWM周期は104 nsから218,453,000 nsの間で指定することができます。

pwm_configure

このAPIはPWMポートを構成します。

int pwm_configure (unsigned char port, int duty_ns, int period_ns)

…これらは:

  • port: 構成するPWMポート番号: 0, 1, 2, 3
  • duty_ns: PWM波形のアクティブなパルス幅のナノ秒
  • period_ns: PWM波形の全体周期のナノ秒

pwm_enable

このAPIはPWMポートを有効にします。

int pwm_enable (unsigned char port)

…これらは:

  • port: 有効にするPWMポート番号: 0, 1, 2, 3

pwm_disable

このAPIはPWMポートを無効にします。

int pwm_disable (unsigned char port)

…これらは:

  • port: 無効にするPWMポート番号: 0, 1, 2, 3

補助API

debug_print

このAPIはホストのデバッグ・コンソール(例えば/dev/ttymcu1)へMCUのデバッグ・メッセージを出力します。

void debug_print(int level, const char *fmt, ...)

…これらは:

  • level: 出力するメッセージのデバッグ・レベルを以下の中から1つ選択します: DBG_FATAL | DBG_ERROR | DBG_WARNING | DBG_INFO | DBG_DEBUG
  • fmt: 書式文字列

mcu_sleep

このAPIはMCUアプリケーションをスリープさせます。

void mcu_sleep(int ticks)

…これらは:

  • ticks: 1単位10 msでEdison MCUのスリープ時間

time_ms

このAPIはMCUが起動してから経過したミリ秒数を返します。この数は1193時間経過後にオーバーフローしてゼロへ戻ります。

unsigned long time_ms()

…これらは:

  • 返り値: 経過したミリ秒の数

time_us

このAPIはMCUが起動してから経過したマイクロ秒数を返します。この数は71分でオーバーフローしてゼロへ戻ります。

unsigned long time_us()

…これらは:

  • 返り値: 経過したマイクロ秒の数

mcu_delay

このAPIはアプリケーションをしばらくポーズ(休止)しますが、アプリケーションはスリープしません。1単位(10ミリ秒)以上のスリープを行うためのアプリケーションのニーズがあるのであれば、いつでもmcu_sleepを呼び出します。

int mcu_delay(int delay_us)

…これらは:

  • delay_us: ポーズするミリ秒単位の数
  • 返り値: 成功すれば0

mcu_snprintf

snprintfのシンプル版です。

void mcu_snprintf(char *buf, unsigned int size, const char *fmt, ...)

…これらは:

  • buf: データを格納するバッファーの位置
  • size: バッファーのサイズ
  • fmt: 書式文字列
  • 返り値: 書き込んだ文字の数

注記:このAPIがサポートするのは%d, %x, %sのみです。

api_version

このAPIはAPIのバージョンを返します。

int api_version()

…これらは:

  • 返り値: メジャー・バージョン番号を100の倍数、これにマイナー・バージョン番号を加えた数

まとめ

現時点で使用できるMCU SDKのAPIを解説するページを意訳してみました。MCU SDKを使用してMCUアプリケーションを記述するための参考になるのではないかと思います。現時点で足りないと思われる要素については遠慮なくIntel Coporationにリクエストするのがよいかと思います。

元々はRTOSで動作するMCUによって、リアルタイムな応答が可能になるのではないかとされていましたが、この仕様ではそのあたりに物足りなさが残るように感じます。Intel Edisonをそれらの分野で応用するにあたって問題があると感じる場合には、ぜひともフィード・バックをIntel Corporationに対してしていただければと思います。

いろいろと書きましたが、それはそれとして、MCU SDKでMCUアプリケーションを開発する方々にとって、少しでも参考にしていただければ幸いです。

※Intel Corporationあるいは関連会社より削除の要請があった場合には予告なく削除しますので、あらかじめご了承ください。


  • インテル株式会社による表現がそうなっているので、それに合わせています。
  • インテル株式会社による表現がそうなっているので、それに合わせています。
  • 質問者の技術レベルに応じて必要な回答を用意するのは、非常に高いスキルと多くの時間を必要とするものです。私はこれらのサービスが可能な状態にはありません。
  • 訳注:かなり強引な意訳です。間違っていたらすみません。
  • 訳注:ここでいう「ボー・レート」とは、いわゆる「ボー・レート」のことです。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です