Armadilloフォーラム

Cactusphereソフトウェアマニュアルの改善ポイント

magicpocket

2020年7月17日 12時00分

ソフトウェアマニュアルにそってCactusphere110接点入力モデルをインストールした際につまずいた点をまとめます。

対象:
ドキュメント: Cactusphere100シリーズ ソフトウェアマニュアル Version 1.0.0 2020/06/26
範囲    : 1〜50ページ (51ページ以降のカスタマイズや運用は試していません。)

1. 全体的感想

とても丁寧に書かれたマニュアルだと思います。
・誤植がほぼない
・途中に挟まれているメモや注意書きが親切

2. つまずいた点、改良が望まれる点

[24ページ:USB給電方法]
24ページの接続例はVINに9V〜24Vの電源をワイヤーで供給する図になっていますが、初めてCactusphereを試してみる状況ではUSB給電を使う人が多いと思います。USB給電の図があると親切だと思います。わざわざハードウェアマニュアルを見なくて済むと楽です。

[25ページ:工場出荷状態で機能を確認する]
アプリケーションの動作仕様が「Lowであるポート数分だけLEDが点滅する」になっていて、ポート数がゼロのとき消灯したままです。これだといつ起動が成功したのかがわかりません。起動が完了したことを判定できるLED表示があるとわかりやすいと思います。一例として「ポート数ゼロの時は1回点滅、1個の時は2回点滅・・・」のようになっていたらわかりやすいと思います。

[26ページ:電源断方法の追加]
フットスイッチを繋げてLED点滅を確認し次にドアセンサーを追加しようとしましたが、Cactusphereの電源を切る正しい手順がわかりませんでした。LinuxベースのRaspberry Piではshutdown操作が必要ですが、Cactusphereの場合どうなっているのかがわかりませんでした。

[28ページ:CactusphereをPCに接続するタイミング]
4.2.2.4.でrecoverを実行しますが、その前にCactusphereをPCに接続しておく必要があります。コマンド例の後に「作業をする上で」という注意書きをおくのではなく、コマンド例の前にPC接続手順を本文として書いてある方がわかりやすいと思います。
また、PCに接続した時、接続に成功しているかどうかを調べる手順があるといいと思います。例えば
azsphere device list-attached
など。

[30ページ:無線LAN接続が成功したかどうか調べたい]
無線LANの設定をしたとき、設定が成功したのかやWiFi接続に成功したのかを知りたくなります。WiFiの状態を調べるコマンド
azsphere device wifi show
が記載されていると助かります。また、SSIDやpassphraseを間違えて入力した場合に、設定を消去できるようにコマンド例が記載されていると親切だと思います。

[30ページ:Ethernetの設定が成功したかどうか調べたい]
無線LANと同様に、設定に成功したのかどうかを調べる方法が記載されていると親切です。また、無線LANとEthernetの両方を設定した場合に、
・片方しか接続できていない場合は、それが自動的に通信に使われるのか
・両方接続されている場合、どちらの接続が使われるのか
の説明があるといいと思います。

[31ページ:Cactusphere接点入力モデル用のアプリケーションテンプレートのURLの設置場所]
アプリケーションテンプレートのURLを見つけるのにかなり手間取りました。マニュアルにはCactusphereのGitHubページのURLが書いてあるので、それがURLだと勘違いしました。開いてみるとGitHubページが表示されますが、そのどこにアプリケーションテンプレートのURLがあるのかすぐにはわかりませんでした。
リリースページのURL(https://github.com/Cactusphere/Cactusphere-100/releases)を書いておき、画面例の図でアプリケーションテンプレートのURLの場所をハイライトしておいた方が良いと思います。

[32ページ:Azure IoT Centralアプリーケーション作成の料金プラン]
私はAzureを触るのが初めてだったので、料金プランの選択でかなり迷いました。
・無料プランを選択してもソフトウェアマニュアルに記載されている手順を全て実行できるのかどうか。
・Standard1や2を選択した場合、ソフトウェアマニュアルに記載されている手順を全て実行した場合にどれぐらい課金されるのか。また、手順実行後にAzureの設定を放置した場合、将来課金される可能性があるのか。
・課金を選んだ場合、サブスクリプションをどうやって作成すれば良いのか。
これらがわからなかったので判断が難しかったのですが、結局無料プランを選択しました。
ソフトウェアマニュアルにどういう課金プランを選択すれば良いのかの説明があると助かります。

[33ページ:プライマリ証明書の管理画面を開く方法]
Azure Sphere Centralの画面仕様がマニュアル記載の画面例と異なっていたのでつまずきました。フォーラムで助けていただいたので前に進めました。

[37ページ:ビルド済みパッケージの取得場所]
37ページにはGitHubのトップページのURLが書いてあるので、そこを開いてソースコードのzipファイルをダウンロードしてしまいました。ここにはリリースページのURLを記載し、かつ、画面例でダウンロードすべきzipファイルのリンク位置を示すておくと良いと思います。

[38ページ:マニフエストの修正後の例]
38ページの例では、AllowedConnectionsの要素が2行しかありません。これを見ながらマニフェストを編集したので、"iotc-・・・」という情報を転記するのを忘れてしまいました。例にこの情報が書いてあれば間違えなかったと思います。

[38ページ:の参照先]
リリースノートはAzure Sphere SDKのリリースノートだと誤解してしまいました。38ページには「4.2.1.チュートリアル環境」との説明があり、4.2.1.を見に行くと4.2.2.2.にSDKのインストールの説明があるためだと思います。
CactusphereのGitHubのリリースノートページのURLを記載して、そこを見るようにはっきり説明した方が良いと思います。

3.その他気が付いた点

ソフトウェアマニュアルの改版にはそれなりに時間がかかると思いますので、それまでは修正・追記コメントをCactusphereのWebページに掲載していただけると、つまずかずに済むと思います。

また、azsphereコマンドが長いので、PDFファイルからコピペしようとすると改行コードが含まれてしまい、コマンドラインへのペーストが面倒になります。コマンド例を集めたtxtファイルを置いていただけると助かります。

以上


コメント

at_keitaro.takahashi

2020年7月20日 12時52分

高橋です。

貴重なご意見、ありがとうございます。
頂いた改善点について、今後のアップデートで順次修正する予定です。

よろしくお願いいたします。