Skip to content

Commit

Permalink
docs: refactor instruction (#65)
Browse files Browse the repository at this point in the history 
* docs: refactor introduction

* chore: apply pre-commit

* chore: return to old link.
  • Loading branch information
@knorrrr
knorrrr authored Jul 10, 2024
1 parent a769099 commit 8e30bc6
Show file tree
Hide file tree
Showing 16 changed files with 215 additions and 223 deletions.
Binary file added docs/assets/top_image.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
0 docs/assets/where-to-start.drawio.svg → ...elopment/images/where-to-start.drawio.svg
View file
File renamed without changes
16 changes: 14 additions & 2 deletions docs/development/main-module.ja.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,21 @@ Autoware-Microを活用することにより、本大会での課題となる：

![racing-diagram](./images/architecture/racing_simple.png)

昨年度の取り組みはこちらのアドベントカレンダーにまとめられていますので参考にしてみてください。
## ワークスペースの構成

[アドベントカレンダー](https://qiita.com/advent-calendar/2023/jidounten-ai)
参考までに本大会で使用しているワークスペースの構成は以下となります。

docker-dev

![dev](./images/docker/dev.drawio.svg)

docker-eval

![eval](./images/docker/eval.drawio.svg)

## 参加者有志の参考記事

参加者有志が取り組んでくださった取り組みは[Advent Calendar](https://qiita.com/advent-calendar/2023/jidounten-ai)にまとめられていますので参考にしてみてください。

どれから読もうか迷った方は2023年度コミュニティ貢献賞を受賞した田中新太さんが記載してくれた[こちらの記事](https://qiita.com/Arata-stu/items/4b03772348dca4f7ef89)から読み進めると良いと思います。

Expand Down
Empty file added docs/development/reference.en.md
View file
Empty file.
82 changes: 82 additions & 0 deletions docs/development/reference.ja.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# 参考

## 変更点の取り込み

大会環境の重大なアップデートがあった際には適宜アナウンスがあります。
参考までにこちらに記載しています。以下を実行してください。

Dockerのupdate

```bash
docker pull ghcr.io/automotiveaichallenge/autoware-universe:humble-latest
```

Repositoryのupdate

```sh
cd aichallenge2024 # path to aichallenge2024
git pull origin/main
```

## 描画ありAWSIMの導入

AWSIMのシミュレーション画面を確認したい方は、[こちら](../setup/visible-simulation.ja.md)の手順に従って描画ありAWSIMの導入を行ってください。

## Debug用にTerminalを3つ用意して開発したい場合 (参考)

`Alt+Ctrl+T`で１つ目のターミナルを立ち上げてから、以下のコマンド`Ctrl+Shift+P`で貼り付けた後に`Enter`で実行します。

```bash
cd ~/aichallenge-2024
./docker_run.sh dev cpu
```

```bash
cd /aichallenge
bash run_simulator.bash
```

`Alt+Ctrl+T`で2つ目のターミナルを立ち上げてから、以下のコマンド`Ctrl+Shift+P`で貼り付けた後に`Enter`で実行します。

```bash
cd ~/aichallenge-2024
./docker_run.sh dev cpu
```

```bash
cd /aichallenge
bash run_autoware.bash
```

`Alt+Ctrl+T`で3つ目のターミナルを立ち上げてから、以下のコマンド`Ctrl+Shift+P`で貼り付けた後に`Enter`で実行します。

```bash
cd ~/aichallenge-2024
./docker_run.sh dev cpu
```

```bash
cd /aichallenge
ros2 topic pub --once /control/control_mode_request_topic std_msgs/msg/Bool '{data: true}' >/dev/null
```

下記の様な画面が表示されたら起動完了です。終了するには各ターミナル上でCTRL + Cを入力します。
![autoware](./images/autoware.png)

## TroubleShooting

!!! warning

基本的には、ChatGPTやGoogle検索で解決できる項目は多いです。それでも解決しない質問については、エラーのログの抜粋と添付をお願いします。

Q. `docker_run.sh: 行 35: rocker: コマンドが見つかりません`

A. [rockerのインストール](../setup/docker.ja.md)をお願いします。

Q. `WARNING unable to detect os for base image 'aichallenge-2024-dev', maybe the base image does not exist`

A. Dockerイメージのビルドをお願いします。

Q. Dockerがpullできません。

A. `newgrp docker`か`sudo service docker restart`でdockerの再起動またはUbuntuの再起動をお願いします。
122 changes: 10 additions & 112 deletions docs/development/workspace-usage.ja.md
View file
Original file line number Diff line number Diff line change
@@ -1,119 +1,17 @@
# ワークスペース
# AIチャレンジの進め方

## 大会用リポジトリのビルド・実行
![Where-to-start](./images/where-to-start.drawio.svg)

大会用リポジトリでは、実際の動作環境はすべてDocker内で完結して提供されています。リポジトリの利用は以下の流れで行います。
AIチャレンジではオープンソースソフトウェアを駆使しています。運営から提供されるコードとウェブプラットフォームを利用することで、初期開発フェーズをスキップし、競技のテーマに合わせた開発をすぐに開始できます。
このアプローチには、「車輪の再発明」を避けることができるという大きな利点があります。さらに、誰でも気軽に大会に参加でき、一貫した評価基準で大会を運営できるというメリットもあります。

1. 大会環境のDockerイメージのビルド
2. Dockerコンテナ上でのAutowareのビルド
3. Dockerコンテナ上でのAutowareとシミュレータの同時起動
初めて参加される方々は、先人たちが築き上げた基盤の上に立ち、自動運転に必要な機能がほとんど揃っている状態からスタートします。これからは、コミュニティによる「取り組みの公開」を通じて、競技領域での独自の開発を深めるチャンスです。
さらに、自動運転の理解を深めるために、運営が用意した「[Autoware Practice](../course/index.ja.md)」やROS 2のコミュニティが提供する「[ROS 2](https://docs.ros.org/en/humble/Tutorials.html)」の学習プログラムを活用することをお勧めします。

## 大会環境のDockerイメージのビルド
既にチャレンジに参加された方々には、ご自身の経験を公開し、コミュニティに貢献して大会の発展に寄与していただければと思います。皆さんの積極的な参加が、大会をさらに充実させることに繋がります。

大会用リポジトリに入ります。
※AIチャレンジで開発する上でベースとなるソースコードは[大会用リポジトリ](https://github.com/AutomotiveAIChallenge/aichallenge-2024/tree/main/aichallenge/workspace/src/aichallenge_submit)内で提供されています。

```bash
cd ~/aichallenge-2024
```
参加者の皆様にはこちらのコードやパラメータをカスタマイズすることで開発を進めていただきますが、Autowareに不慣れな方はまずは[入門講座](../course/index.ja.md)を一通りやっていただくことをお勧めします。

Dockerイメージのビルドを行います。

```bash
./docker_build.sh dev
```

```bash
docker images
```

で以下のイメージが生成されていることを確認しましょう。

```txt
aichallenge-2024-dev latest df2e83a20349 33 minutes ago 8.9GB
```

## Dockerコンテナ上でのAutowareのビルド

以下を実行してDockerコンテナを立ち上げます。

```bash
cd ~/aichallenge-2024
./docker_run.sh dev cpu
```

特に何も変わっていないように見えますが、上記のコマンドを実行すると環境がDockerコンテナ内部に移行します。今の環境がDockerコンテナ内かどうかは以下のコマンドで何も表示されていないかを確認するのがわかりやすいです。

```bash
ls ~
```

Dockerコンテナ内で以下を実行してAutowareをビルドします。

```bash
cd /aichallenge
./build_autoware.bash
```

## Dockerコンテナ上でのAutowareとSimulatorの実行

Autowareのビルド後、以下のコマンドを実行します。

```bash
./run_evaluation.bash
```

下記の様な画面が表示されたら起動完了です。終了するにはターミナル上でCTRL + Cを入力します。
![autoware](./images/autoware.png)

## Debug用にTerminalを3つ用意して開発したい場合 (参考)

`Alt+Ctrl+T`で１つ目のターミナルを立ち上げてから、以下のコマンド`Ctrl+Shift+P`で貼り付けた後に`Enter`で実行します。

```bash
cd ~/aichallenge-2024
./docker_run.sh dev cpu
```

```bash
cd /aichallenge
bash run_simulator.bash
```

`Alt+Ctrl+T`で2つ目のターミナルを立ち上げてから、以下のコマンド`Ctrl+Shift+P`で貼り付けた後に`Enter`で実行します。

```bash
cd ~/aichallenge-2024
./docker_run.sh dev cpu
```

```bash
cd /aichallenge
bash run_autoware.bash
```

`Alt+Ctrl+T`で3つ目のターミナルを立ち上げてから、以下のコマンド`Ctrl+Shift+P`で貼り付けた後に`Enter`で実行します。

```bash
cd ~/aichallenge-2024
./docker_run.sh dev cpu
```

```bash
cd /aichallenge
ros2 topic pub --once /control/control_mode_request_topic std_msgs/msg/Bool '{data: true}' >/dev/null
```

下記の様な画面が表示されたら起動完了です。終了するには各ターミナル上でCTRL + Cを入力します。
![autoware](./images/autoware.png)

### ワークスペースの構成 (参考)

参考までにこちらにワークスペースの構成を記載しておきます。

docker-dev

![dev](./images/docker/dev.drawio.svg)

docker-eval

![eval](./images/docker/eval.drawio.svg)
※リポジトリ内のコードを使わず独自に開発する方など、各種仕様について知りたい方は[インターフェース仕様](../specifications/interface.ja.md)、[シミュレータ仕様](../specifications/simulator.ja.md)のページを参照してください。
128 changes: 24 additions & 104 deletions docs/getting-started.ja.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,128 +2,48 @@

このページではAIチャレンジでの一連の流れを記載します。

## オンライン採点環境へのアクセスと提出
本大会ではUbuntu 22.04を搭載したPC一台のみで参加ができます。

!!! info

オンライン採点環境へのアクセスから提出までの所要時間は５分程度です

本大会では、オンライン環境に提出ファイル（ソースコードの圧縮ファイル）をアップロードすることで自動採点が行われ、順位が決定されます。オンライン採点環境には[こちら](https://aichallenge-board.jsae.or.jp/live)からアクセスしてください。

次の3ステップでまずはオンライン採点環境を使ってみましょう！

1. 自動運転AIチャレンジへの参加申込みがまだ済んでいない方は[こちら](https://docs.google.com/forms/d/e/1FAIpQLSc0xFCrNS_J5Bl2g2RIZ694B5p9vOhlav9hrwgumtBrQuQ0RQ/viewform)から登録お願いします。
まずオンライン採点環境の利用を行い、その後環境構築・開発と進んでいきます。

2. 申込みを完了し、ユーザー登録がまだ済んでいない方はSlackでの案内に従って登録お願いします。ログイン情報が登録メールアドレスに送られてきます．

3. アクセスが出来たら、一度ソースコードの提出をしてみましょう。
下の赤ボタンからサンプルコードの圧縮ファイルをダウンロードして、オンライン採点環境の「UPLOAD」ボタンからそのままアップロードすることで提出ができます。

[サンプルコードの圧縮ファイルのダウンロード](https://drive.google.com/file/d/19LU70cgeg48R6stEXjvwDp1pTT25OjeN){ .md-button .md-button--primary .banner-button }

![submit](./preliminaries/images/submit.png)
## 自動運転AIチャレンジ2024への[参加登録](https://docs.google.com/forms/d/e/1FAIpQLSc0xFCrNS_J5Bl2g2RIZ694B5p9vOhlav9hrwgumtBrQuQ0RQ/viewform)

以下の手順では環境構築から開発、ファイルの提出までの流れを説明します。
参加登録が済んでいない方は上記リンクから登録をお願いします。

## 必要なもの
## [オンライン採点環境](https://aichallenge-board.jsae.or.jp/live)へのアクセスと提出

### Ubuntu PC

[推奨環境](./setup/requirements.ja.md)を満たすPCが必要ですが、推奨と書かれているものについては満たしていなくても動作することは可能です。ただし、推奨よりも低いスペックで動作させる場合ROS2側での実行速度が安定せずシミュレーションの実行の度に挙動が大きく変わってしまう可能性があります。

!!! warning

Windows環境しかお持ちでない方は、Ubuntu22.04のインストールをお願いいたします。Windows環境と同じディスクにUbuntu環境を入れることもできますが、不慣れな場合Windows環境を破壊してしまう可能性があるため、新しく外付けまたは内蔵SSDを購入したうえでそちらへのインストールをすることを強くお勧めします。
本大会では、オンライン環境に提出ファイル（ソースコードの圧縮ファイル）をアップロードすることで自動採点が行われ、順位が決定されます。

次の4ステップでまずはオンライン採点環境を使ってみましょう！
!!! info

Ubuntuのインストール方法については[こちらの記事](https://qiita.com/kiwsdiv/items/1fa6cf451225492b33d8)が参考になります。

## AIチャレンジの進め方

![Where-to-start](./assets/where-to-start.drawio.svg)

AIチャレンジではオープンソースソフトウェアを駆使しています。運営から提供されるコードとウェブプラットフォームを利用することで、初期開発フェーズをスキップし、競技のテーマに合わせた開発をすぐに開始できます。
このアプローチには、「車輪の再発明」を避けることができるという大きな利点があります。さらに、誰でも気軽に大会に参加でき、一貫した評価基準で大会を運営できるというメリットもあります。

初めて参加される方々は、先人たちが築き上げた基盤の上に立ち、自動運転に必要な機能がほとんど揃っている状態からスタートします。これからは、コミュニティによる「取り組みの公開」を通じて、競技領域での独自の開発を深めるチャンスです。
さらに、自動運転の理解を深めるために、運営が用意した「[Autoware Practice](./course/index.ja.md)」やROS 2のコミュニティが提供する「[ROS 2](https://docs.ros.org/en/humble/Tutorials.html)」の学習プログラムを活用することをお勧めします。

既にチャレンジに参加された方々には、ご自身の経験を公開し、コミュニティに貢献して大会の発展に寄与していただければと思います。皆さんの積極的な参加が、大会をさらに充実させることに繋がります。

## AIチャレンジの環境構築

`Alt+Ctrl+T`でターミナルを立ち上げてから、以下に従ってコマンド`Ctrl+Shift+P`で貼り付けた後に`Enter`で実行します。

- [ワークスペースのクローン](./setup/workspace-setup.ja.md)
- [Dockerのインストール](./setup/docker.ja.md)
- [AWSIMのダウンロード](./setup/headless-simulation.ja.md)

## 大会用リポジトリのビルド・実行

環境構築が終わってから再度`Alt+Ctrl+T`でターミナルを立ち上げてから、以下に従ってコマンド`Ctrl+Shift+P`で貼り付けた後に`Enter`で実行します。

[ワークスペースの使い方説明ページ](./development/workspace-usage.ja.md)

## AIチャレンジでの開発の進め方

ビルド・実行が終わってからメインモジュールの解説ページを読みながら実際に開発してみましょう。

[メインモジュールについての解説ページ](./development/main-module.ja.md)

※AIチャレンジで開発する上でベースとなるソースコードは[大会用リポジトリ](https://github.com/AutomotiveAIChallenge/aichallenge-2024/tree/main/aichallenge/workspace/src/aichallenge_submit)内に提供されています。参加者の皆様にはこちらのコードやパラメータをカスタマイズすることで開発を進めていただきますが、Autowareに不慣れな方はまずは[入門講座](./course/index.ja.md)を一通りやっていただくことをお勧めします。

※リポジトリ内のコードを使わず独自に開発する方など、各種仕様について知りたい方は[インターフェース仕様](./specifications/interface.ja.md)、[シミュレータ仕様](./specifications/simulator.ja.md)のページを参照してください。

## ソースコードの提出

完成したコードの提出は[オンライン採点環境](https://aichallenge-board.jsae.or.jp/live)から行います。提出は以下の手順で行ってください。

1. ソースコードの圧縮
2. ローカル評価環境での動作確認
3. オンライン採点環境への提出

各手順の方法については[提出ページ](./preliminaries/submission.ja.md)を参照してください。

## 参考

### 変更点の取り込み

大会環境の重大なアップデートがあった際には適宜アナウンスがあります。
参考までにこちらに記載しています。以下を実行してください。

Dockerのupdate

```bash
docker pull ghcr.io/automotiveaichallenge/autoware-universe:humble-latest

```
オンライン採点環境へのアクセスから提出までの所要時間は５分程度です

Repositoryのupdate
1. 自動運転AIチャレンジの参加登録後。ログイン情報が登録メールアドレスに送られてきます．

```sh
cd aichallenge2024 # path to aichallenge2024
git pull origin/main
```
2. [オンライン採点環境](https://aichallenge-board.jsae.or.jp/live)にアクセスし、メールアドレス記載の資格情報を用いてログインしてください。

### 描画ありAWSIMの導入
3. アクセスが出来たら、一度ソースコードの提出をしてみましょう。
下の赤ボタンからサンプルコードの圧縮ファイルをダウンロードします。

AWSIMのシミュレーション画面を確認したい方は、[こちら](./setup/visible-simulation.ja.md)の手順に従って描画ありAWSIMの導入を行ってください。
4. オンライン採点環境の「UPLOAD」ボタンからそのままアップロードすることで提出ができます。

### TroubleShooting
[サンプルコードの圧縮ファイルのダウンロード](https://drive.google.com/file/d/19LU70cgeg48R6stEXjvwDp1pTT25OjeN){ .md-button .md-button--primary .banner-button }

!!! warning
![submit](./preliminaries/images/submit.png)

基本的には、ChatGPTやGoogle検索で解決できる項目は多いです。それでも解決しない質問については、エラーのログの抜粋と添付をお願いします。
## [AIチャレンジの環境構築](./setup/requirements.ja.md)

Q. `docker_run.sh: 行 35: rocker: コマンドが見つかりません`
上記リンクより環境構築を行って下さい。
!!! info

A. [rockerのインストール](./setup/docker.ja.md)をお願いします。
本大会ではUbuntu 22.04を搭載したPC一台のみで参加ができます。

Q. `WARNING unable to detect os for base image 'aichallenge-2024-dev', maybe the base image does not exist`
## [AIチャレンジでの開発の進め方](./development/workspace-usage.ja.md)

A. Dockerイメージのビルドをお願いします。
上記リンクより、実際に開発してみましょう！

Q. Dockerがpullできません。
## [ソースコードの提出](./preliminaries/submission.ja.md)

A. `newgrp docker`か`sudo service docker restart`でdockerの再起動またはUbuntuの再起動をお願いします。
完成したコードの提出は[オンライン採点環境](https://aichallenge-board.jsae.or.jp/live)から行います。
上記リンクより提出セットアップを行ってください。
2 changes: 2 additions & 0 deletions docs/index.ja.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Japan Automotive AI Challenge 2024

![top_image](./assets/top_image.jpg)

## コンセプト

!!! info
Expand Down
Loading

0 comments on commit 8e30bc6

Please sign in to comment.