search

chirimen-oh / chirimen.org

Tutorials for CHIRIMEN
https://tutorial.chirimen.org/
Mozilla Public License 2.0
3 stars 7 forks source link

CHIRIMEN with micro:bit をフルセットチュートリアル化＆同時に全体の見直し #75

Open dynamis opened 4 years ago

dynamis commented 4 years ago

現在 CHIRIMEN with micro:bit は CHIRIMEN for RasPi 学習者向けの追加的なものという位置づけで簡便なガイドと Example だけを提供している:

https://chirimen.org/chirimen-micro-bit/

集まっての講習会・イベントなどが難しい昨今、RasPi ではなく安価に入手可能な microbit (+ブレークアウトボード + 電池ボックス) だけで遠隔学習をし易くするため、RPi 向けのチュートリアルを読まず最初から micro:bit 用のチュートリアルだけ読めば済むようにしたい。

そのためには現 Rpi チュートリアルをベースにガッツリ書き直しが必要。全部見直すことになるなら、この際以下の issue を合わせて実行したい:

optional だがついでに出来るなら:

dynamis commented 4 years ago

検討事項:

kou029w commented 4 years ago
hiyohiyo commented 3 years ago

極力シンプルなのが良いのでCSBへの全面移行に賛成です。 チュートリアルの作成・検証にも携わらせてください。Raspi版との差分はかなりありますが、まずはスタートアップガイドをベースにLチカの周期を変更するところからでしょうか？

satakagi commented 3 years ago

micro:bitの場合、内蔵デバイスを使う例がありますが、これをどのように位置づけるか？

汎用性(micro:bit以外の環境でも使いまわせる)とか標準性(webGPIO,I2C(これらも標準化には遠いがそれでもそれを意識して仕様を作っているかどうかは大きい))とかがあまり感じられるものでないので、副次的な位置づけなことに異論はないと思う。

ただ、micro:bit以外に何も使わず動作することは、はじめの一歩として動作を確認してもらえる　という点で価値が感じられる。(CHIRIMEN with micro:bitは、 CHIRIMEN for RPiと比べてWebBTで接続するというハマりポイントがある）

そこで、章立てとして、　第０章？：CHIRIMEN with micro:bitの動作確認　という第一章のひとつ前のところで内蔵デバイス使ったチュートリアル入れるのが良いでしょうかね。

dynamis commented 3 years ago

極力シンプルなのが良いのでCSBへの全面移行に賛成です。

micro:bit (PC) や RasPi4 以降であれば CSB (VS Code) 重たい問題もあまりなくなりますし、基本は CSB で、JSBin や JSFiddle は紹介だけ Appendix 的に残すか、完全に消して RasPi3 で non CSB したい人は古いアーカイブサイトを見てくださいとするか (Examples ページも (github pages ではスナップショットビルド残せないので Netlify でアーカイブを作る) ですかね。

チュートリアルの作成・検証にも携わらせてください。Raspi版との差分はかなりありますが、まずはスタートアップガイドをベースにLチカの周期を変更するところからでしょうか？

ありがとうございます＆こちらが滞っていて申し訳ないです。仰るとおり既存のを両対応にかき分けです。 下記の構成案で進めるなら micro:bit 用 hello real world 部分は raspi との依存関係無しで独立で書けるので、そこをどんな形でも md と画像で書いていって頂けたりすると嬉しかったりします。

micro:bitの場合、内蔵デバイスを使う例がありますが、これをどのように位置づけるか？ ... snip ... そこで、章立てとして、　第０章？：CHIRIMEN with micro:bitの動作確認　という第一章のひとつ前のところで内蔵デバイス使ったチュートリアル入れるのが良いでしょうかね。

現状 Hello Real World、基礎編、応用編、発展編とありますが、ボード毎の導入、共通のチュートリアル、作品例などの大きく三つに分離し、ボード毎の導入の中に Hello Real World も microbit 内蔵デバイスも入れてはどうでしょう。

チュートリアル再構成案

パスは新サイト内のパス、URL はベースの現コンテンツ

ボード毎のコンテンツ:

チュートリアル

作品例

サポートデバイス

パーツリストなどは md で表を書くのではなく yml 編集してその結果を生成する方向にした方が良さそうだなと思ってます。

こういうのと同じような感じで: https://github.com/gatsbyjs/gatsby/blob/master/docs/sites.yml https://www.gatsbyjs.org/showcase/

システム＆テーマ

サイトのシステムとしては既存の Jekyll 実装案はいろいろごにょごにょしたのですが結局それは捨てて、モダンな JAMSTACK の代表格 GatsbyJS を使ったサイト想定に切り替えています。チュートリアルではないトップページなどは React の jsx コードを書くがチュートリアルの執筆に関しては md 書くだけというのは基本変わりません。

ベースのテーマとしては色々確認してみたのですが何だかんだ GatsbyJS 公式サイトチュートリアルの実装が最高に思えるのでそちらをフォーク (gastby 全体の monorepo の一部になってるなどそのままフォークして使うのはしにくいのは諦める): https://www.gatsbyjs.org/tutorial/ https://github.com/gatsbyjs/gatsby/blob/master/docs/tutorial/

次点としてはシンプルで真っ当な starter が https://github.com/hasura/gatsby-gitbook-starter でしたがちょっと物足りない

satakagi commented 3 years ago

オリジナルの/raspi/readme.mdをベースに、micro:bit用に書き換えをしてみました。 確かに、機種ごとの導入編を設ければば、その後の章を大体共通化　というのは可能かもと思いました。

lang: ja permalink: /microbit/

CHIRIMEN with micro:bit チュートリアル

CHIRIMEN with micro:bit を用いた IoT システムプロトタイピングスキル習得のためのチュートリアル資料です。

JavaScript プログラミング未経験者は、ページ下部で紹介している資料・サイトも参照しつつご覧ください。

準備編

micro:bitをwebアプリでコントロールするための準備と最初の動作確認を行います

動作確認を兼ねて、micro:bitの内蔵センサーやLED等を操作できます。

デバイス操作～基礎編

シンプルな GPIO 入出力や I2C センサーの操作方法を学びましょう。

デバイス操作～応用編

いろいろな I2C デバイスを繋いだり組み合わせたりすることで IoT プロトタイピングを体験しましょう。

IoT編

いよいよインターネットを介してデバイスをリモートで操作したりセンシングしたりする、Internet of Things (IoT)の基礎を体験しましょう。

ここまでできたら Example 集を見ていろいろなデバイスを試したり自分で好きなものを作ってみましょう。

発展編

ここまでの例では飽き足らない人のための発展的な使い方を紹介します。興味のあるものがあればお試しください。 注意: 学校や講習会などで参加者全員で学習する場合は応用編までで十分です。

対応デバイスと Example 集

CHIRIMEN with micro:bit 対応デバイスのドライバ・回路図・サンプルコードをセットにした Example 集を用意しています。

対応デバイスのリスト : 下記サンプルへのリンク付き

いずれのExamplesも、元のソースコードは こちら に収録されています。

Appendix, Tips, FAQ, Links etc...

JavaScript 未経験者・初心者向けの資料集や、良くある質問、Tips やテクニック、デバッグとトラブルシューティングのページを用意しています。

## Latest Version / 最新版 Latest version of this document is hosted on https://tutorial.chirimen.org/microbit/ このサイトの最新オンライン版は https://tutorial.chirimen.org/microbit/ でご覧頂けます
dynamis commented 3 years ago

オリジナルの/raspi/readme.mdをベースに、micro:bit用に書き換えをしてみました。

おぉ、ページの md が issue コメントに書かれるパターン。ありがとうございます。

ちなみに、ざっくりこんな雰囲気で作って行けそうかなとテストしているもの netlify にもデプロイしておいてみるとこんな感じです。

https://chirimen-org-gatsby.netlify.app/tutorial/

テーマとして使えそうか、振る舞いはどんなものか確認段階なので色々途中です。

このテーマについてのコメント

近日、何とかまとめてこうすれば編集できると分かる＆確定させる様にします。。。

kou029w commented 3 years ago

チュートリアル再構成案 https://github.com/chirimen-oh/tutorials/issues/75#issuecomment-664727783

コンテンツの構成に関してまったく異論ないです :+1: どのgitリポジトリか分からないですがいずれにせよ /docs 以下が Jekyll のサイトでいうルートディレクトリに相当するという感じで、それぞれパスに対応するようにMarkdownファイルを配置していくということですかね?

satakagi commented 3 years ago

今、codesandboxでCHIRIMEN with micro:bitのexamplesを動かそうとしてみてハマりました。 ブラウザネイティブのconsoleを見るとrequestDevice() called from cross-origin iframe.　となっているので クロスオリジンiframe関係のエラー？　これはcodesandboxを使った場合でも解消可能？ https://codesandbox.io/s/github/chirimen-oh/chirimen-micro-bit/tree/master/examples/GPIO0?module=main.js

kou029w commented 3 years ago

iframeの中ではWeb Bluetooth APIにアクセスすることができませんので新しいタブで開き直すなどする必要あります > @satakagi

例: https://github.com/chirimen-oh/chirimen-micro-bit/blob/ca645c26078fa5fb1a2f8df82e919828ea6f9e89/polyfill/demo/main.js

satakagi commented 3 years ago

codesandboxなら、これを押すわけですね！　これははハマりますね～ちゃんと説明に書こう。 csb0

ということは、デバッグコンソールの類は、ウェブサービス側でラップされたものを使うのではなく、ブラウザネイティブのもの(ctrl+shift+I)を使う形で説明するということか。　個人的にはその方がわかりやすい:-)

codesandbox全然よく理解できてないんですが、この新しいウィンドウ(タブ)でページが開けるということは、テンポラリに？このwebAppsがcodesandboxのサービスでだれでも見られるように公開されるということなんですね。　確かに別のPCで、この開いたwindowのURL(ランダムな文字列が入ったもの)を開いてみたらちゃんと見られた！

hiyohiyo commented 3 years ago

こんなご時世ではございますが、近々札幌に帰省することにしたので、子供たちとも試してみたいと思います。 LEDなどを別途使うのも重要ですが、内蔵の温度センサーや傾きセンサーなどが使えるだけでも面白いので、「第０章？：CHIRIMEN with micro:bitの動作確認」は、アリだと思います。物理的なパーツが何もなくてもとりあえず色々試せますからね。

satakagi commented 3 years ago

今、↑のcodesandboxの話を含めて　初期設定・動作確認の章　素案作成中です！

satakagi commented 3 years ago

https://github.com/chirimen-oh/tutorials/tree/master/microbit https://github.com/chirimen-oh/tutorials/blob/master/microbit/hello_microbit.md

dynamis commented 3 years ago

/docs 以下が Jekyll のサイトでいうルートディレクトリに相当するという感じで、それぞれパスに対応するようにMarkdownファイルを配置していくということですかね?

はい。そんなイメージです。 チュートリアルその他でデザインがある程度シンプル＆固定のものは Markdown (実際には Markdown ではなく MDX) で記述して、そうではない特殊な部分は React (JSX) で記述するという構成です。

Gatsbyjs サイトからフォークするより素の Docusaurus v2 から始めた方が良いのではと言う突っ込みを受けてそちらもお試し中 (こちらになる可能性が今のところ高い) です: https://github.com/chirimen-oh/chirimen.org-docusaurus https://chirimen-org-docusaurus.netlify.app/

ひとまず今のまま jekyll の markdown でガンガン編集していってくだされば何処かでまとめて or 少しずつ移行作業を行います。

codesandbox全然よく理解できてないんですが、この新しいウィンドウ(タブ)でページが開けるということは、テンポラリに？このwebAppsがcodesandboxのサービスでだれでも見られるように公開されるということなんですね。　確かに別のPCで、この開いたwindowのURL(ランダムな文字列が入ったもの)を開いてみたらちゃんと見られた！

はい。netlify などがコミットや PR に対してガンガン deploy していくのと同様に CSB もファイル編集して保存する度にそれをガンガン deploy してくれており、それを単独で開くのがその別ウィンドウ表示、エディタないでのプレビューはそれを iframe 読み込みしているだけになります。

今、↑のcodesandboxの話を含めて　初期設定・動作確認の章　素案作成中です！ https://github.com/chirimen-oh/tutorials/tree/master/microbit https://github.com/chirimen-oh/tutorials/blob/master/microbit/hello_microbit.md

私が遅くて手が回ってないところをカバー頂きありがとうございます！！！ そのまま tutorial repo で編集し続けて頂ければ、前述の通り適当なタイミングで新デザインサイト側に移植作業します。

その際に (可能な範囲で) 気に留めて頂けると嬉しい点は以下の通りです:

dynamis commented 3 years ago

あると嬉しい (作りたい、誰か書いて欲しい) 新規独立ページ:

kou029w commented 3 years ago
satakagi commented 3 years ago

https://github.com/chirimen-oh/tutorials/blob/master/microbit/GPIO_starter.md 本格的にRPiとコンテンツの大部分が一致しているはずのページを　RPiページをベースに　ひとまず何も考えずに編集してみました。 たしかに大部分は共通　ただ、細かい部分で違うところがチマチマある・・

satakagi commented 3 years ago

https://github.com/chirimen-oh/tutorials/blob/master/microbit/GPIO_basic.md も作ってみました。githubpagesが更新されないのは気のせいでしょうか？

kou029w commented 3 years ago

githubpagesが更新されないのは気のせいでしょうか？

Deploy Logによるとmicrobit/GPIO_starter.mdからのrelative_include examples/section0/s0.htmlなどの部分で参照に失敗していたようです。一旦その部分をコメントアウトしてデプロイしました。s0.htmlを正しく配置するなどしてもらえれば直ると思いますのでご確認ください。 > @satakagi

要修正

dynamis commented 3 years ago

CodeSandboxガイド … 作成中

ありがとうございます！ぱっと見ではあとこのあたりの記載でしょうか？

WIMC リモート開催文脈としては (あるいはプログラミングの遠隔講義一般にだけど) 次の 2 つは独立ページで説明が欲しい:

dynamis commented 3 years ago

連携サービス申し込みノート: Algolia OSS https://www.algolia.com/for-open-source/ Crowdin OSS https://crowdin.com/page/open-source-project-setup-request Crowdin Academic https://crowdin.com/page/academic-license-project-setup-request

satakagi commented 3 years ago

chirimen micro:bitのI2C examplesを倍増させ、tutorialsのSection4の準備ができました。（Section4で紹介しているデバイスの半分がexamplesになかった）

hiyohiyo commented 3 years ago

遅ればせながらチュートリアルを確認中です。 https://tutorial.chirimen.org/microbit/gpio_basic

中盤にある以下の部分が解決できないようです。これは、最終的に変換されるものなのでしょうか？ {% cloudinary imgs/section1/LEDOnOff.gif alt="LED On/Offをブラウザ画面上のボタンクリックで実施" %}

それとも、https://github.com/chirimen-oh/tutorials/tree/master/raspi/imgs/section1/LEDOnOff.gif にリンクするように修正した方が良いですか？

kou029w commented 3 years ago

@hiyohiyo はい、そちらはJekyll(とそのプラグイン)によって、適切なリンクに変換されるので、そのままで構いません。(Feedbackの画像の埋め込みを参照)

kou029w commented 3 years ago

CHIRIMEN with micro:bit をフルセットチュートリアル化＆同時に全体の見直し #75

前者は完了済みですかね? 後者の全体の見直しはIssueを分けたほうが良さそうに思います。いかがでしょうか。