テキストプロトコル¶

概要¶

Kurikintonsファームウェアはシリアル通信（UART）でホストPCと通信します。このドキュメントはテキストコマンドベースのシリアルプロトコルを定義します。

注意: このドキュメントは ENABLE_TEXT_PROTOCOL=1 の開発用ビルドで有効です。本番環境ではバイナリープロトコルが有効になっています。

目次¶

通信基本仕様
プロトコル構造
テキストコマンド仕様
コマンド詳細リファレンス
センサーデータ出力形式
エラーハンドリング
実装例
トラブルシューティング

通信基本仕様¶

物理層¶

パラメーター	値
ボーレート	115200 bps
データビット	8
ストップビット	1
パリティ	なし
フロー制御	なし

フレームフォーマット¶

[コマンド行]\n
[レスポンス行]\n
[コマンド行]\n
[レスポンス行]\n

コマンド形式: テキスト行（英数字、スペース、アンダースコア、ハイフンを含む）
レスポンス形式: JSON Lines（JSONL、1行の有効なJSON + 改行）
改行コード:
入力: \n または \r\n (デバイス側で両方対応)
出力: \n (デバイス側で送出)

コマンド行の制限¶

制限項目	値
最大長	64 バイト
引数の最大数	2個
引数の区切り	スペース or タブ
大文字／小文字	区別なし（大文字に自動変換）
無効な文字	英数字、スペース、タブ、アンダースコア、ハイフン以外は拒否

入力タイムアウト¶

コマンド入力のタイムアウトを500msに設定
500ms以内に入力データが到達しない場合、それまでの部分行をコマンドとして受け入れる

プロトコル構造¶

コマンド解析フロー¶

[テキスト入力]
    ↓
[長さチェック（<=64byte）]
    ↓
[文字種チェック（英数字+記号）] → [エラー] → ERROR_INVALID_CHAR
    ↓
[トークン化（スペース区切り）]
    ↓
[コマンド名を大文字に変換]
    ↓
[エイリアス解決（C→SET_POLL_COUNT など）]
    ↓
[コマンドテーブルで検索]
    ↓
[ハンドラー関数実行]
    ↓
[JSONLレスポンス送信]

コマンドキュー¶

設計: FIFO キュー (容量: 10コマンド)
コマンド受信時に queue_command() でキューに追加
メインループで process_queued_text_command() により1コマンドずつ処理
利点：ホスト側は高速送信可能、デバイス側は順序保証でゆっくり処理

コマンドエイリアス¶

素早く入力できるように、すべてのコマンドに1文字エイリアスを割り当てています。

エイリアス	フルコマンド	用途
`C`	`SET_POLL_COUNT`	検出待ちのポーリング回数の設定
`T`	`SET_THRESHOLD`	DACスレッショルド値の設定
`G`	`GET_THRESHOLD`	DACスレッショルド値の取得
`V`	`GET_VERSION`	バージョンの取得
`R`	`RESET`	設定をリセット
`I`	`SET_INTERVAL`	検出間隔の設定（テスト用）
`S`	`STATUS`	ステータスの取得
`L`	`LED`	LEDの制御
`U`	`UPTIME`	起動時刻を取得
`H`	`HELP`	ヘルプを取得

使用例:

C 200       <- SET_POLL_COUNT 200 と同等
T 1 500     <- SET_THRESHOLD 1 500 と同等
G 2         <- GET_THRESHOLD 2 と同等
S           <- STATUS と同等

テキストコマンド仕様¶

コマンド一覧表¶

#	コマンド	エイリアス	引数	説明
1	`SET_POLL_COUNT`	`C`	`<count>`	ポーリング数設定（1-1000）
2	`SET_THRESHOLD`	`T`	`<ch> <val>`	DAC閾値設定
3	`GET_THRESHOLD`	`G`	`<ch>`	DAC閾値取得
4	`GET_VERSION`	`V`	なし	ファームウェアバージョン取得
5	`RESET`	`R`	なし	設定をデフォルトにリセット
6	`SET_INTERVAL`	`I`	`<ms>`	検出間隔設定（テスト用）
7	`STATUS`	`S`	なし	全設定状態表示
8	`LED`	`L`	`<ch\\|ALL> <ON\\|OFF>`	LED手動制御
9	`UPTIME`	`U`	なし	起動からの経過時間表示
10	`HELP`	`H`	なし	ヘルプ表示

コマンド詳細リファレンス¶

1. `SET_POLL_COUNT` - 検出待ちのポーリング回数の設定¶

SET_POLL_COUNT <count>
C <count>

1サイクルあたりのGPIO検出ポーリング数を設定します。値が大きいほど消費電力も増加します。 countは[1, 1000]の範囲で指定できます。

デフォルト値: 100

レスポンス（成功）:

{"poll_count": 200}

レスポンス（エラー例）:

{"status":"error","command":"SET_POLL_COUNT","error":"Missing required argument: <count>","code":1}
{"status":"error","command":"SET_POLL_COUNT","error":"Invalid argument format","code":1}
{"status":"error","command":"SET_POLL_COUNT","error":"Poll count out of range [1, 1000]","code":2}

使用例:

# フルコマンド
SET_POLL_COUNT 150

# エイリアス
C 150

# レスポンス
{"poll_count": 150}

備考: 変更は即座に有効になります。検出ポーリング数が増加すると、ファームウェアのCPU使用率が上がります。

2. SET_THRESHOLD - DAC閾値設定¶

機能: 指定したチャネルのDAC（デジタル・アナログ・コンバータ）閾値を設定します。SPI経由でハードウェア制御回路に即座に反映されます。

構文:

SET_THRESHOLD <ch> <val>
T <ch> <val>

引数:

ch: チャネル番号（1, 2, 3）
val: 閾値（0～4095）

閾値エンコーディング: 内部的には以下の計算で2バイトに変換されます

byte1 = 0x10 + (threshold >> 6)
byte2 = (threshold << 2) & 0xFF

例：threshold=1234 → byte1=0x23, byte2=0x4A

レスポンス（成功）:

{"channel": 1, "threshold": 100}

レスポンス（エラー例）:

{"status":"error","command":"SET_THRESHOLD","error":"Missing required argument","code":1}
{"status":"error","command":"SET_THRESHOLD","error":"Channel out of range [1, 3]","code":2}
{"status":"error","command":"SET_THRESHOLD","error":"Threshold value out of range [0, 4095]","code":2}
{"status":"error","command":"SET_THRESHOLD","error":"Failed to set threshold via SPI","code":3}

使用例:

# チャネル1の閾値を500に設定
SET_THRESHOLD 1 500

# エイリアス使用
T 2 1200

# 全チャネルの閾値を低く設定（高感度）
T 1 100
T 2 100
T 3 100

# レスポンス
{"channel": 1, "threshold": 500}

備考: SPI通信に失敗した場合（エラーコード3）、ハードウェアが接続されていないか、I2Cアドレスの競合がないか確認してください。

3. GET_THRESHOLD - DAC閾値取得¶

機能: 指定したチャネルの現在のDAC閾値を取得します。

構文:

GET_THRESHOLD <ch>
G <ch>

引数:

ch: チャネル番号（1, 2, 3）

レスポンス（成功）:

{"channel": 1, "threshold": 500}

レスポンス（エラー例）:

{"status":"error","command":"GET_THRESHOLD","error":"Missing required argument: <ch>","code":1}
{"status":"error","command":"GET_THRESHOLD","error":"Channel out of range [1, 3]","code":2}

使用例:

# チャネル1の現在の閾値を確認
G 1

# レスポンス
{"channel": 1, "threshold": 500}

# 全チャネル確認
G 1
G 2
G 3

4. GET_VERSION - バージョン取得¶

機能: ファームウェアのバージョン情報を取得します。

構文:

GET_VERSION
V

引数: なし

レスポンス:

{"version": "1.7.4"}

使用例:

V

# レスポンス
{"version": "1.7.4"}

備考: バージョンは include/config.h の FIRMWARE_VERSION マクロで定義されています。

5. RESET - 設定リセット¶

機能: 全ての設定値をデフォルトにリセットします。

構文:

RESET
R

引数: なし

リセット対象:

Poll count: 100
Interval: 0ms
Threshold (ch1-3): 0
LED状態: OFF

レスポンス:

{"status":"ok","message":"Configuration reset to defaults"}

使用例:

R

# レスポンス
{"status":"ok","message":"Configuration reset to defaults"}

備考: リセット後、全テスト設定が初期化されます。

6. SET_INTERVAL - 検出間隔設定¶

機能: 連続した検出イベント間の最小間隔を設定します。主にテスト・デバッグ用で、DEBUG_DETECTION_MODE=1 の開発ビルドでのみ有効です。

構文:

SET_INTERVAL <ms>
I <ms>

引数:

ms: ミリ秒（0～60000）

デフォルト値: 0ms（間隔制限なし）

レスポンス（成功）:

{"interval_ms": 5000}

レスポンス（エラー例）:

{"status":"error","command":"SET_INTERVAL","error":"Missing required argument: <ms>","code":1}
{"status":"error","command":"SET_INTERVAL","error":"Invalid argument format","code":1}
{"status":"error","command":"SET_INTERVAL","error":"Interval out of range [0, 60000]","code":2}

使用例:

# 5秒間隔でテスト検出を実施
SET_INTERVAL 5000

# または
I 5000

# 間隔制限なし（デフォルト）
I 0

# レスポンス
{"interval_ms": 5000}

使用場面:

実コズミック線なしでファームウェア動作テスト
セッサーデータ出力フォーマット検証
定期的なデータロギング動作確認

7. STATUS - 全設定状態表示¶

機能: デバイスの全設定値と動作状態をJSONL形式で表示します。

構文:

STATUS
S

引数: なし

レスポンス:

{
  "version": "1.7.4",
  "poll_count": 100,
  "interval_ms": 0,
  "threshold1": 0,
  "threshold2": 0,
  "threshold3": 0,
  "uptime_ms": 12345678
}

使用例:

S

# レスポンス
{"version":"1.7.4","poll_count":100,"interval_ms":0,"threshold1":500,"threshold2":600,"threshold3":700,"uptime_ms":123456789}

备注: 複数のキー・バリュー対が1行のJSONLで返されます。パーザーはこれを1つのオブジェクトとして処理してください。

8. LED - LED手動制御¶

機能: 各チャネルのLED（フィードバック）を手動で制御します。

構文:

LED <ch|ALL> <ON|OFF>
L <ch|ALL> <ON|OFF>

引数:

ch|ALL: チャネル番号（1, 2, 3）または "ALL"
state: "ON" または "OFF"（大文字に統一）

対応するGPIOピン:

LED ch1: GPIO14
LED ch2: GPIO26
LED ch3: GPIO33

レスポンス（成功）:

{"channel": 1, "state": "ON"}
{"channel": "ALL", "state": "OFF"}

レスポンス（エラー例）:

{"status":"error","command":"LED","error":"Missing required argument","code":1}
{"status":"error","command":"LED","error":"Invalid channel or state format","code":1}
{"status":"error","command":"LED","error":"Channel out of range [1, 3]","code":2}

使用例:

# チャネル1のLEDをON
LED 1 ON

# チャネル2のLEDをOFF
L 2 OFF

# 全LEDをON
LED ALL ON

# レスポンス
{"channel": 1, "state": "ON"}
{"channel": "ALL", "state": "OFF"}

備考: LEDはハードウェアフィードバック用で、ファームウェア内部の検出状態と同期しません。

9. UPTIME - 起動時刻表示¶

機能: デバイス起動からの経過時間を表示します。

構文:

UPTIME
U

引数: なし

レスポンス:

{
  "uptime_ms": 123456789,
  "days": 1,
  "hours": 10,
  "minutes": 17,
  "seconds": 36,
  "milliseconds": 789
}

使用例:

U

# レスポンス（起動から約1日10時間17分36秒787ms後）
{"uptime_ms":123456789,"days":1,"hours":10,"minutes":17,"seconds":36,"milliseconds":789}

計算例:

uptime_ms = 123,456,789
days = 123456789 / (24 * 3600 * 1000) = 1
remaining_ms = 123456789 - (1 * 86400000) = 36656789
hours = 36656789 / (3600 * 1000) = 10
minutes = ((36656789 % 3600000) / 60000) = 17
seconds = ((36656789 % 60000) / 1000) = 36
milliseconds = 36656789 % 1000 = 789

備考:

ESP32は ~49日でuptime_msがオーバーフロー（uint32_t限界）します
ENABLE_TIMESTAMP=1 の場合、センサー出力に自動的にuptime_msが含まれます

10. HELP - ヘルプ表示¶

機能: 全コマンドのリストと使用法を表示します。

構文:

HELP
H

引数: なし

レスポンス:

{
  "commands": [
    {
      "alias": "C",
      "command": "SET_POLL_COUNT",
      "args": "<count>",
      "description": "Set poll count (1-1000)"
    },
    {
      "alias": "T",
      "command": "SET_THRESHOLD",
      "args": "<ch> <val>",
      "description": "Set DAC threshold for channel"
    },
    {
      "alias": "G",
      "command": "GET_THRESHOLD",
      "args": "<ch>",
      "description": "Get DAC threshold for channel"
    },
    {
      "alias": "V",
      "command": "GET_VERSION",
      "args": "",
      "description": "Get firmware version"
    },
    {
      "alias": "R",
      "command": "RESET",
      "args": "",
      "description": "Reset configuration to defaults"
    },
    {
      "alias": "I",
      "command": "SET_INTERVAL",
      "args": "<ms>",
      "description": "Set detection interval for testing (0-60000ms)"
    },
    {
      "alias": "S",
      "command": "STATUS",
      "args": "",
      "description": "Show all configuration values"
    },
    {
      "alias": "L",
      "command": "LED",
      "args": "<ch|ALL> <ON|OFF>",
      "description": "Control LEDs manually"
    },
    {
      "alias": "U",
      "command": "UPTIME",
      "args": "",
      "description": "Show uptime since boot"
    },
    {
      "alias": "H",
      "command": "HELP",
      "args": "",
      "description": "Show this help message"
    }
  ]
}

使用例:

H

# レスポンス（複数行のJSONで返される）
{"commands":[{"alias":"C","command":"SET_POLL_COUNT",...}, ... ]}

備注: HELPコマンドは複雑な入れ子構造のJSONを返すため、JSONパーサーの動作確認に有用です。

センサーデータ出力形式¶

テキストコマンドとは別に、コズミック線イベント検出時に自動的にセンサーデータが出力されます。出力形式は STREAM_FORMAT フラグで制御します。

形式選択¶

ビルド時に以下のいずれかを選択：

# SSV（デフォルト、後方互換）
task build

# TSV（タブ区切り）
PLATFORMIO_BUILD_FLAGS="-DSTREAM_FORMAT=1" pio run -e esp32dev-release

# CSV（カンマ区切り、ヘッダー付き）
PLATFORMIO_BUILD_FLAGS="-DSTREAM_FORMAT=2" pio run -e esp32dev-release

# JSONL（JSON Lines）
PLATFORMIO_BUILD_FLAGS="-DSTREAM_FORMAT=3" pio run -e esp32dev-release

出力フィールド¶

必須フィールド （常に出力）:

signal1: チャネル1検出カウント (0-100)
signal2: チャネル2検出カウント (0-100)
signal3: チャネル3検出カウント (0-100)
adc: ADC読み値 (0-4095, 12ビット)

オプションフィールド:

tmp_c: 気温 (℃) - ENABLE_BME280=1 時
atm_pa: 気圧 (Pa) - ENABLE_BME280=1 時
hmd_pct: 湿度 (%) - ENABLE_BME280=1 時
uptime_ms: 起動からの経過時間 (ms) - ENABLE_TIMESTAMP=1 時
duration_us: 前イベントからの経過時間 (μs) - ENABLE_TIMESTAMP=1 時

フォーマット例¶

STREAM_FORMAT=0: SSV (Space-Separated Values)

100 85 92 2048 25.35 1013.25 45.67
100 85 92 2048 25.35 1013.25 45.67 123456 5234000

STREAM_FORMAT=1: TSV (Tab-Separated Values)

100 85 92 2048 25.35 1013.25 45.67
100 85 92 2048 25.35 1013.27 45.68 123456 5234000

STREAM_FORMAT=2: CSV (Comma-Separated Values)

signal1,signal2,signal3,adc,tmp_c,atm_pa,hmd_pct
100,85,92,2048,25.35,1013.25,45.67
100,85,92,2048,25.35,1013.27,45.68

STREAM_FORMAT=3: JSONL (JSON Lines)

{"signal1":100,"signal2":85,"signal3":92,"adc":2048,"tmp_c":25.35,"atm_pa":1013.25,"hmd_pct":45.67}
{"signal1":100,"signal2":85,"signal3":92,"adc":2048,"tmp_c":25.35,"atm_pa":1013.27,"hmd_pct":45.68,"uptime_ms":123456,"duration_us":5234000}

フィールド仕様¶

フィールド	型	範囲	単位	説明
signal1	uint8_t	0-100	カウント	チャネル1検出数
signal2	uint8_t	0-100	カウント	チャネル2検出数
signal3	uint8_t	0-100	カウント	チャネル3検出数
adc	uint16_t	0-4095	ADC値	12ビットADC読み値
tmp_c	float	-50～100	℃	BME280温度センサー
atm_pa	float	30000～110000	Pa	BME280気圧センサー
hmd_pct	float	0-100	%	BME280湿度センサー
uptime_ms	uint32_t	0～4294967295	ms	ESP32内部タイマー（~49日でオーバーフロー）
duration_us	uint64_t	0～18446744073709551615	μs	前イベントからの時間

エラーハンドリング¶

エラー応答形式¶

全てのエラーは以下のJSON形式で返されます：

{
  "status": "error",
  "command": "SET_POLL_COUNT",
  "error": "Poll count out of range [1, 1000]",
  "code": 2
}

エラーコード¶

コード	意味	例
1	引数形式エラー	引数が整数ではない、必須引数がない
2	範囲外エラー	値が min-max 範囲外
3	ハードウェアエラー	SPI通信失敗、センサー初期化失敗

よくあるエラー¶

エラー: Poll count out of range [1, 1000]

原因: 指定した値が1～1000の範囲外
解決: 有効な範囲内の値を指定してください
例: SET_POLL_COUNT 150

エラー: Channel out of range [1, 3]

原因: チャネル番号が1～3ではない
解決: チャネル1、2、3のいずれかを指定してください
例: SET_THRESHOLD 1 500

エラー: Threshold value out of range [0, 4095]

原因: 閾値が0～4095の範囲外
解決: 有効な範囲内の値を指定してください
例: SET_THRESHOLD 1 2000

エラー: Invalid argument format

原因: 数値として解析できない引数が渡された
解決: 引数が整数であることを確認してください
例: SET_POLL_COUNT 100  （×SET_POLL_COUNT abc）

エラー: Missing required argument

原因: 必須引数が指定されていない
解決: コマンド構文を確認して引数を追加してください
例: SET_THRESHOLD 1 500  （×SET_THRESHOLD 1）

実装例¶

Python を使用したホスト側実装¶

import serial
import json
import time

class Kurikintons:
    def __init__(self, port='/dev/ttyUSB0', baudrate=115200):
        self.ser = serial.Serial(port, baudrate, timeout=1)
        time.sleep(2)  # デバイス起動待ち

    def send_command(self, command):
        """コマンドを送信してレスポンスを受け取る"""
        self.ser.write((command + '\n').encode())
        response = self.ser.readline().decode().strip()
        try:
            return json.loads(response)
        except json.JSONDecodeError:
            return {"error": "Invalid JSON response", "raw": response}

    def get_version(self):
        """バージョン取得"""
        return self.send_command("V")

    def set_poll_count(self, count):
        """ポーリング数設定"""
        return self.send_command(f"C {count}")

    def set_threshold(self, channel, value):
        """閾値設定"""
        return self.send_command(f"T {channel} {value}")

    def get_threshold(self, channel):
        """閾値取得"""
        return self.send_command(f"G {channel}")

    def get_status(self):
        """全設定状態取得"""
        return self.send_command("S")

    def reset(self):
        """設定リセット"""
        return self.send_command("R")

    def get_uptime(self):
        """起動時刻取得"""
        return self.send_command("U")

    def led_on(self, channel):
        """LED ON"""
        return self.send_command(f"L {channel} ON")

    def led_off(self, channel):
        """LED OFF"""
        return self.send_command(f"L {channel} OFF")

    def close(self):
        self.ser.close()


# 使用例
if __name__ == "__main__":
    device = Kurikintons('/dev/ttyUSB0')

    # バージョン確認
    print(device.get_version())
    # {'version': '1.7.4'}

    # ポーリング数を200に設定
    print(device.set_poll_count(200))
    # {'poll_count': 200}

    # 全ステータス確認
    print(device.get_status())
    # {'version': '1.7.4', 'poll_count': 200, ...}

    # 起動時刻確認
    print(device.get_uptime())
    # {'uptime_ms': 123456789, 'days': 1, ...}

    device.close()

Arduino/C++ を使用したホスト側実装¶

#include <Serial.h>
#include <ArduinoJson.h>

void setup() {
    Serial.begin(115200);

    // コマンド送信例
    send_command("V");      // バージョン取得
    delay(100);

    send_command("C 150");  // ポーリング数を150に設定
    delay(100);

    send_command("S");      // ステータス表示
    delay(100);
}

void loop() {
    // レスポンス受け取り
    if (Serial.available() > 0) {
        String json_line = Serial.readStringUntil('\n');

        // JSONパース
        StaticJsonDocument<256> doc;
        DeserializationError error = deserializeJson(doc, json_line);

        if (!error) {
            // パース成功
            if (doc.containsKey("version")) {
                Serial.print("Version: ");
                Serial.println(doc["version"].as<const char*>());
            }
            if (doc.containsKey("poll_count")) {
                Serial.print("Poll Count: ");
                Serial.println(doc["poll_count"].as<int>());
            }
        }
    }
}

void send_command(const char* command) {
    Serial.println(command);
}

シェルスクリプトを使用した実装¶

#!/bin/bash

# シリアルポート設定
SERIAL_PORT="/dev/ttyUSB0"

# コマンド送信関数
send_command() {
    local cmd=$1
    echo "$cmd" > "$SERIAL_PORT"
    sleep 0.5
    read -t 1 response < "$SERIAL_PORT"
    echo "Response: $response"
}

# バージョン確認
echo "Getting version..."
send_command "V"

# ポーリング数設定
echo "Setting poll count to 200..."
send_command "C 200"

# ステータス表示
echo "Getting status..."
send_command "S"

トラブルシューティング¶

症状: コマンドが応答しない¶

原因1: ボーレート不一致

確認: シリアルターミナル設定が 115,200 baud になっているか
解決: ターミナルを 115,200 baud に設定し直す

原因2: テキストプロトコルが無効

確認: ビルド時に ENABLE_TEXT_COMMAND=1 が設定されているか
解決: v1またはv2ビルド (task v1:build または task v2:build) を使用する

原因3: デバイスが起動していない

確認: ESP32の電源LEDが点灯しているか
解決: USB電源ケーブルを再接続する

症状: エラーレスポンスが返される¶

エラーコード1（引数形式エラー）

{"status":"error","code":1}

原因: 引数が数値でない、または不足している解決: コマンド構文を確認して正しい引数を指定してください

エラーコード2（範囲外エラー）

{"status":"error","code":2}

原因: 引数の値が有効範囲外解決: 引数の有効範囲を確認してください

エラーコード3（ハードウェアエラー）

{"status":"error","code":3}

原因: SPI通信失敗、センサー初期化失敗解決: ハードウェア接続を確認してください

症状: JSON応答が文字化けしている¶

原因: 文字コード設定不一致

解決: ターミナルの文字コードをUTF-8に設定してください

症状: コマンドキューがいっぱいになった¶

原因: コマンドを高速送信しすぎている

現象: キュー容量が10コマンドに達している
解決: コマンド間に100ms以上の遅延を入れてください

device.send_command("C 100")
time.sleep(0.1)  # 100ms待機
device.send_command("S")

症状: LED制御が効かない¶

原因1: GPIO接続なし

確認: LED接続GPIOピンが正しいか（GPIO14, 26, 33）
解決: ハードウェア配線を確認してください

原因2: コマンド構文誤り

確認: LED <ch|ALL> <ON|OFF> 形式になっているか
解決: LED 1 ON のように正しい構文で送信してください

症状: タイムスタンプが0になっている¶

原因: ENABLE_TIMESTAMP=0

確認: ビルド時に ENABLE_TIMESTAMP=1 が設定されているか
解決: dev ビルド使用時は自動的に有効化されます

ベストプラクティス¶

ホスト側通信¶

コマンド間隔の確保

device.send_command("C 100")
time.sleep(0.1)  # 100ms以上の間隔
device.send_command("S")

タイムアウト処理

import time
timeout = 1.0  # 秒
start = time.time()
while time.time() - start < timeout:
    if self.ser.in_waiting > 0:
        break

JSONパース時のエラーハンドリング

try:
    response = json.loads(data)
    if response.get("status") == "error":
        print(f"Error code: {response.get('code')}")
except json.JSONDecodeError:
    print(f"Invalid JSON: {data}")

複数コマンドの順序保証

# キューが満杯になるのを避けるため、レスポンス待ちを含める
for cmd in commands:
    device.send_command(cmd)
    device.wait_response(timeout=1.0)

デバイス側設定¶

ポーリング数の最適化
高感度が必要な場合: 200-500
通常運用: 100
低消費電力: 50-100
閾値チューニング
初期値: 0 (最高感度)
ノイズが多い場合: 500-2000
高感度必要: 0-500
テスト環境での設定

# ベンチテスト用設定（コズミック線なし）
I 5000        # 5秒間隔で自動検出生成
C 100         # ポーリング数100
S             # ステータス確認

変更履歴¶

バージョン	日時	変更内容
1.0.0	2025-11-22	初版作成（v1.7.4対応）

参考リンク¶

ドキュメント作成者: Kurikintons 開発チーム 対象ファームウェア: v1.7.4 以降 最終更新: 2025-11-22

テキストプロトコル¶

概要¶

目次¶

通信基本仕様¶

物理層¶

フレームフォーマット¶

コマンド行の制限¶

入力タイムアウト¶

プロトコル構造¶

コマンド解析フロー¶

コマンドキュー¶

コマンドエイリアス¶

テキストコマンド仕様¶

コマンド一覧表¶

コマンド詳細リファレンス¶

1. SET_POLL_COUNT - 検出待ちのポーリング回数の設定¶

2. SET_THRESHOLD - DAC閾値設定¶

3. GET_THRESHOLD - DAC閾値取得¶

4. GET_VERSION - バージョン取得¶

5. RESET - 設定リセット¶

6. SET_INTERVAL - 検出間隔設定¶

7. STATUS - 全設定状態表示¶

8. LED - LED手動制御¶

9. UPTIME - 起動時刻表示¶

10. HELP - ヘルプ表示¶

センサーデータ出力形式¶

形式選択¶

出力フィールド¶

フォーマット例¶

フィールド仕様¶

エラーハンドリング¶

エラー応答形式¶

エラーコード¶

よくあるエラー¶

実装例¶

Python を使用したホスト側実装¶

Arduino/C++ を使用したホスト側実装¶

シェルスクリプトを使用した実装¶

トラブルシューティング¶

症状: コマンドが応答しない¶

症状: エラーレスポンスが返される¶

症状: JSON応答が文字化けしている¶

症状: コマンドキューがいっぱいになった¶

症状: LED制御が効かない¶

症状: タイムスタンプが0になっている¶

ベストプラクティス¶

ホスト側通信¶

デバイス側設定¶

変更履歴¶

参考リンク¶

1. `SET_POLL_COUNT` - 検出待ちのポーリング回数の設定¶