arduino-oxidizer 1.0.0
A python tool to build Rust project for Arduino and write it.
License: MIT

# oxidizer (arduino-oxidizer)

<a name="english-version" />
<a href="#japanese-version"><b>日本語版が使用できます ／ Japanese version is avaialble</b></a>

A python tool to build Rust project for Arduino and write it.

## Installation

### Requirements

- `python3`
- `pip`
- `cargo`
- A rust project configurated to build for Arduino, or an elf file to write
  - If you need to make a project for it, a template [loxygenK/arduino-on-rust_template](https://github.com/loxygenK/arduino-on-rust_template) is available.
- `avrdude`

### Installation

You can install oxidizer with`pip`

```bash
pip install arduino-oxidizer
```

Note: The package's name to install is **`arduino-oxidizer`**, not `oxidizer`. 

## How to use

### Build and write a Cargo project configured for Arduino

Oxidizer builds the project using `cargo`, and write to Arduino. The target ELF file is searched based on `cargo.toml`.

```bash
oxidizer <Serial port to write>
```

#### example

```
$ cd /path/to/cargo/projects/root
$ oxidizer /dev/ttyUSB0
[i] Building 'some-nice-project' ...
[i] >> cargo build
    Updating crates.io index
    Finished dev [unoptimized + debuginfo] target(s) in 2.30s
[v] Building succeeded! Writing to Arduino...
[i] >> avrdude -C/etc/avrdude.conf -patmega328p -carduino -P/dev/ttyUSB0 -Uflash:w:target/avr-atmega
328p/debug/some-nice-project.elf:e

avrdude: AVR device initialized and ready to accept instructions

Reading | ################################################## | 100% 0.00s

/* ...... */

avrdude: 4982 bytes of flash verified

avrdude: safemode: Fuses OK (E:00, H:00, L:00)

avrdude done.  Thank you.

[v] All works done!
```

### Build and write in release mode

Run with the option `--release` (`-r`) , to build in release mode.

```
$ cd /path/to/cargo/projects/root
$ oxidizer /dev/ttyUSB0 -r
[i] Building 'some-nice-project' in release mode...
[i] >> cargo build --release
    Updating crates.io index
    Finished release [optimized] target(s) in 2.42s

/* ...... */

avrdude done.  Thank you.

[✓] All works done!
```

### Write your own ELF file

Run with the option `--skip-cargo` (`-s`) and `--elf-path` (`-e`) , to skip building a cargo project, and write your own ELF file to Arduino.

```
$ oxidizer --skip-cargo --elf-path my_own_elf_file.elf /dev/ttyUSB0
[i] >> avrdude -C/etc/avrdude.conf -patmega328p -carduino -P/dev/ttyUSB0 -Uflash:w:my_own_elf_file.elf:e

avrdude: AVR device initialized and ready to accept instructions

/* ...... */

avrdude done.  Thank you.

[✓] All works done!
```

## Other options

Various options is available:

```
$ oxidizer --help
usage: oxidizer [-h] [--release] [--cargo-option [Option [Option ...]]]
                [--avrdude-option [Option [Option ...]]] [--avrdude-override] [--avrdude-quite]
                [--skip-cargo] [--elf-path ELF_PATH] [--no-color]
                target

A building helper for the Rust project for Arduino.

positional arguments:
  target                Specify the serial port to write.

optional arguments:
  -h, --help            show this help message and exit
  --release, -r         Let cargo build in release mode
  --cargo-option [Option [Option ...]], -c [Option [Option ...]]
                        Pass options to cargo. Type without '-'!
  --avrdude-option [Option [Option ...]], -a [Option [Option ...]]
                        Pass options to avrdude. Type without '-'!
  --avrdude-override, -A
                        override avrdude's option. Use with '-a'
  --avrdude-quite, -q   Use -q option when avrdude.
  --skip-cargo, -s      Skip building using cargo.
  --elf-path ELF_PATH, -e ELF_PATH
                        Specify ELF file's path. Use target/avr-
                        atmega328p/{debug,release}/{package_name}.elf as default.
  --no-color            Disable color output.
```

| Option               | Abbreviation | Arguments                                               | Description                                                  |
| -------------------- | ------------ | ------------------------------------------------------- | ------------------------------------------------------------ |
| `--release`          | `-r`         | Nothing                                                 | Build the cargo project in release mode.<br />Cannot be used with `--skip-cargo`. |
| `--cargo-option`     | `-c`         | Options to pass to cargo<br />(enumerate without`-`)    | Run cargo with additional options.                           |
| `--avrdude-option`   | `-a`         | Options to pass to avrdude<br /> (enumerate without`-`) | Run avrdude with additional options.                         |
| `--avrdude-override` | `-A`         | Nothing                                                 | Replace the default options to pass to avrdude with the options specified in `--avrdude-option`. |
| `--skip-cargo`       | `-s`         | Nothing                                                 | Skip building a cargo project. Use with`--elf-path`.         |
| `--elf-path`         | `-e`         | The ELF file to write                                   | Specify the ELF file's path to write.                        |
| `--no-color`         | Nothing      | Nothing                                                 | Print logs without ASCII espace sequences.                   |

---



# oxidizer (arduino-oxidizer)

<a name="japanese-version" />
<a href="#english-version"><b>English version is available ／ 英語版が利用できます</b></a>

Pythonで作成された、Rustで書かれたArduinoプロジェクトをビルド・書き込むためのツールです。

## インストール

### 必要なもの

- `python3`
- `pip`
- `cargo`
- Arduino用にビルドできるように構成されたRustのプロジェクト
  または書き込みたいelfファイル
  - よろしければ [loxygenK/arduino-on-rust_template](https://github.com/loxygenK/arduino-on-rust_template) をどうぞ（ダイマ）
- `avrdude`

### インストール

`pip`でインストールできます:

```bash
pip install arduino-oxidizer
```

注意: インストールするパッケージ名は`oxidizer`ではなく**`arduino-oxidizer`**です。 

## 使い方

### Arduino用に構成されたCargoプロジェクトをビルド・書き込み

oxidizerは、`cargo`を用いてビルドを行い、`avrdude`を用いてArduinoへ書き込みを行います。
書き込むELFファイルは`Cargo.toml`から読み込んだプロジェクト名を元に検索されます。

```bash
oxidizer <書き込み先のシリアルポート>
```

#### 例

```
$ cd /path/to/cargo/projects/root
$ oxidizer /dev/ttyUSB0
[i] Building 'some-nice-project' ...
[i] >> cargo build
    Updating crates.io index
    Finished dev [unoptimized + debuginfo] target(s) in 2.30s
[v] Building succeeded! Writing to Arduino...
[i] >> avrdude -C/etc/avrdude.conf -patmega328p -carduino -P/dev/ttyUSB0 -Uflash:w:target/avr-atmega
328p/debug/some-nice-project.elf:e

avrdude: AVR device initialized and ready to accept instructions

Reading | ################################################## | 100% 0.00s

/* ...... */

avrdude: 4982 bytes of flash verified

avrdude: safemode: Fuses OK (E:00, H:00, L:00)

avrdude done.  Thank you.

[v] All works done!
```

### Cargoプロジェクトをリリースモードでビルド・書き込み

`--release`（`-r`）をつけて実行すると、リリースモードでビルドされます。

```
$ cd /path/to/cargo/projects/root
$ oxidizer /dev/ttyUSB0 -r
[i] Building 'some-nice-project' in release mode...
[i] >> cargo build --release
    Updating crates.io index
    Finished release [optimized] target(s) in 2.42s

/* ...... */

avrdude done.  Thank you.

[✓] All works done!
```

### 自作のELFファイルを書き込む

`--skip-cargo`（`-s`）と`--elf-path`（`-e`）を指定して実行すると、Cargoプロジェクトのビルドをスキップし、自作のELFファイルを書き込むことができます。

```
$ oxidizer --skip-cargo --elf-path my_own_elf_file.elf /dev/ttyUSB0
[i] >> avrdude -C/etc/avrdude.conf -patmega328p -carduino -P/dev/ttyUSB0 -Uflash:w:my_own_elf_file.elf:e

avrdude: AVR device initialized and ready to accept instructions

/* ...... */

avrdude done.  Thank you.

[✓] All works done!
```

## 他のオプション

様々なオプションを利用できます:

```
$ oxidizer --help
usage: oxidizer [-h] [--release] [--cargo-option [Option [Option ...]]]
                [--avrdude-option [Option [Option ...]]] [--avrdude-override] [--avrdude-quite]
                [--skip-cargo] [--elf-path ELF_PATH] [--no-color]
                target

A building helper for the Rust project for Arduino.

positional arguments:
  target                Specify the serial port to write.

optional arguments:
  -h, --help            show this help message and exit
  --release, -r         Let cargo build in release mode
  --cargo-option [Option [Option ...]], -c [Option [Option ...]]
                        Pass options to cargo. Type without '-'!
  --avrdude-option [Option [Option ...]], -a [Option [Option ...]]
                        Pass options to avrdude. Type without '-'!
  --avrdude-override, -A
                        override avrdude's option. Use with '-a'
  --avrdude-quite, -q   Use -q option when avrdude.
  --skip-cargo, -s      Skip building using cargo.
  --elf-path ELF_PATH, -e ELF_PATH
                        Specify ELF file's path. Use target/avr-
                        atmega328p/{debug,release}/{package_name}.elf as default.
  --no-color            Disable color output.
```

| オプション           | 省略形 | 引数                                   | 説明                                                         |
| -------------------- | ------ | -------------------------------------- | ------------------------------------------------------------ |
| `--release`          | `-r`   | なし                                   | Cargoプロジェクトをリリースモードでビルドします。<br />`--skip-cargo`と同時に指定することはできません。 |
| `--cargo-option`     | `-c`   | Cargoに渡すオプション(`-`なしで列挙)   | Cargoでビルドする際に、追加でオプションをつけて実行します。  |
| `--avrdude-option`   | `-a`   | avrdudeに渡すオプション(`-`なしで列挙) | avrdudeでビルドする際に、追加でオプションをつけて実行します。 |
| `--avrdude-override` | `-A`   | なし                                   | avrdudeでビルドする際、規定のコマンドを`--avrdude-option`で指定されたものに置き換えます。 |
| `--skip-cargo`       | `-s`   | なし                                   | Cargoでのビルドをスキップします。<br />`--elf-path`と一緒に使用します。 |
| `--elf-path`         | `-e`   | Arduinoに書き込むELFファイルへのパス   | 書き込むELFファイルのパスを指定します。                      |
| `--no-color`         | なし   | なし                                   | ASCIIエスケープシーケンスなしで出力を行います。              |