From 2f2c43ae75e70630e915a4088731cff45fea4176 Mon Sep 17 00:00:00 2001 From: sam-ellis Date: Fri, 10 Jul 2026 18:47:59 +0900 Subject: [PATCH 1/5] Add Clover OMM API --- proto/aegs/clover/v1/clover_service.proto | 29 +++++++++++++++++++++++ proto/aegs/clover/v1/models.proto | 12 +++++++++- 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/proto/aegs/clover/v1/clover_service.proto b/proto/aegs/clover/v1/clover_service.proto index 9b0d42ab..c035b627 100644 --- a/proto/aegs/clover/v1/clover_service.proto +++ b/proto/aegs/clover/v1/clover_service.proto @@ -20,6 +20,13 @@ service CloverService { // TLE が不正な場合は INVALID_ARGUMENT (3) が、最新の TLE と同じものを登録しようとした場合は ALREADY_EXISTS (6) のエラーが返る。 rpc RegisterTLE(RegisterTLERequest) returns (RegisterTLEResponse); + // 指定した衛星の最新の OMM を取得する。 + rpc GetLatestOMM(GetLatestOMMRequest) returns (GetLatestOMMResponse); + + // 指定した衛星の OMM を登録する。 + // OMM が不正な場合は INVALID_ARGUMENT (3) が、最新の OMM と同じものを登録しようとした場合は ALREADY_EXISTS (6) のエラーが返る。 + rpc RegisterOMM(RegisterOMMRequest) returns (RegisterOMMResponse); + // 指定した衛星について利用可能な地上局のリストを取得する。 rpc ListAvailableGroundStations(ListAvailableGroundStationsRequest) returns (ListAvailableGroundStationsResponse); @@ -91,6 +98,28 @@ message RegisterTLEResponse { aegs.clover.v1.TLERecord tle_record = 1; } +message GetLatestOMMRequest { + // OMM を取得する衛星の ID + int64 satellite_id = 1; +} + +message GetLatestOMMResponse { + // 指定された衛星の最新の OMM 情報 + aegs.clover.v1.OMMRecord omm_record = 1; +} + +message RegisterOMMRequest { + // OMM を登録する衛星の ID + int64 satellite_id = 1; + // 登録する OMM（KVN形式） + string kvn = 2; +} + +message RegisterOMMResponse { + // 登録された OMM の情報 + aegs.clover.v1.OMMRecord omm_record = 1; +} + message ListAvailableGroundStationsRequest { // 利用可能な地上局を取得する衛星の ID int64 satellite_id = 1; diff --git a/proto/aegs/clover/v1/models.proto b/proto/aegs/clover/v1/models.proto index d7ca7916..23458034 100644 --- a/proto/aegs/clover/v1/models.proto +++ b/proto/aegs/clover/v1/models.proto @@ -30,6 +30,16 @@ message TLE { string line2 = 2; } +// 登録された OMM の情報。 +message OMMRecord { + // OMM の ID + int64 id = 1; + // 登録された OMM（KVN形式） + string kvn = 2; + // OMM の登録日時 + google.protobuf.Timestamp register_time = 3; +} + // 地上局。 message GroundStation { // 地上局の ID @@ -95,7 +105,7 @@ message Contact { // コンタクトの更新日時。 // 基本的にはステータスの変更時刻を表す google.protobuf.Timestamp update_time = 8; - // リクエスト時の TLE に基づいて計算されたパスの詳細。 + // リクエスト時の軌道情報に基づいて計算されたパスの詳細。 // GetContact の場合にのみ値が設定される。 // コンタクト時刻の前後にパスが見つからなかった場合は値が設定されない PassDetails pass = 9; From c9f7169cb75c4e1015f0dcb28e867f5c2a3accc5 Mon Sep 17 00:00:00 2001 From: sam-ellis Date: Wed, 15 Jul 2026 20:03:26 +0900 Subject: [PATCH 2/5] Added format support for future OMM extensibility --- proto/aegs/clover/v1/clover_service.proto | 12 +++++++++--- proto/aegs/clover/v1/models.proto | 17 +++++++++++++++-- 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/proto/aegs/clover/v1/clover_service.proto b/proto/aegs/clover/v1/clover_service.proto index c035b627..07a068e4 100644 --- a/proto/aegs/clover/v1/clover_service.proto +++ b/proto/aegs/clover/v1/clover_service.proto @@ -101,6 +101,8 @@ message RegisterTLEResponse { message GetLatestOMMRequest { // OMM を取得する衛星の ID int64 satellite_id = 1; + // OMM のフォーマット + aegs.clover.v1.OmmFormat omm_format = 2; } message GetLatestOMMResponse { @@ -111,12 +113,16 @@ message GetLatestOMMResponse { message RegisterOMMRequest { // OMM を登録する衛星の ID int64 satellite_id = 1; - // 登録する OMM（KVN形式） - string kvn = 2; + // 登録する OMM + oneof omm { + // 登録する OMM（KVN形式） + string kvn = 2; + } } message RegisterOMMResponse { - // 登録された OMM の情報 + // 登録された OMM の情報。 + // 形式はリクエストで登録された OMM の形式と同じ。 aegs.clover.v1.OMMRecord omm_record = 1; } diff --git a/proto/aegs/clover/v1/models.proto b/proto/aegs/clover/v1/models.proto index 23458034..ec0f536f 100644 --- a/proto/aegs/clover/v1/models.proto +++ b/proto/aegs/clover/v1/models.proto @@ -34,12 +34,25 @@ message TLE { message OMMRecord { // OMM の ID int64 id = 1; - // 登録された OMM（KVN形式） - string kvn = 2; + // 登録された OMM + oneof omm { + // 登録された OMM（KVN形式） + string kvn = 2; + } // OMM の登録日時 google.protobuf.Timestamp register_time = 3; } +// OMM のフォーマット。 +enum OmmFormat { + // OMM のフォーマットが指定されていない場合の値。 + // リクエストでこの値が指定された場合は、INVALID_ARGUMENT エラーを返す。 + OMM_FORMAT_UNSPECIFIED = 0; + + // OMM のフォーマットが KVN 形式の場合の値 + OMM_FORMAT_KVN = 1; +} + // 地上局。 message GroundStation { // 地上局の ID From 1c38fc8bceb8b5ba17c937200307014ea379080f Mon Sep 17 00:00:00 2001 From: sam-ellis Date: Wed, 15 Jul 2026 20:07:41 +0900 Subject: [PATCH 3/5] Fixed enum name casing for OMMFormat --- proto/aegs/clover/v1/clover_service.proto | 2 +- proto/aegs/clover/v1/models.proto | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/proto/aegs/clover/v1/clover_service.proto b/proto/aegs/clover/v1/clover_service.proto index 07a068e4..3e2ec9b9 100644 --- a/proto/aegs/clover/v1/clover_service.proto +++ b/proto/aegs/clover/v1/clover_service.proto @@ -102,7 +102,7 @@ message GetLatestOMMRequest { // OMM を取得する衛星の ID int64 satellite_id = 1; // OMM のフォーマット - aegs.clover.v1.OmmFormat omm_format = 2; + aegs.clover.v1.OMMFormat omm_format = 2; } message GetLatestOMMResponse { diff --git a/proto/aegs/clover/v1/models.proto b/proto/aegs/clover/v1/models.proto index ec0f536f..8315b529 100644 --- a/proto/aegs/clover/v1/models.proto +++ b/proto/aegs/clover/v1/models.proto @@ -44,7 +44,7 @@ message OMMRecord { } // OMM のフォーマット。 -enum OmmFormat { +enum OMMFormat { // OMM のフォーマットが指定されていない場合の値。 // リクエストでこの値が指定された場合は、INVALID_ARGUMENT エラーを返す。 OMM_FORMAT_UNSPECIFIED = 0; From 36b7dcdc54fe8f29106d2fa288f3fec61ed97e1c Mon Sep 17 00:00:00 2001 From: sam-ellis Date: Thu, 16 Jul 2026 10:41:19 +0900 Subject: [PATCH 4/5] Updated usage documentation to include OMM registration --- docs/usage.md | 57 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 50 insertions(+), 7 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index be4a4859..f62078cf 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -2,7 +2,7 @@ この節では、Clover API を用いて以下の操作を行う方法を説明します。 -1. TLE の登録 +1. OMM または TLE（以下、軌道情報）の登録 2. 予約可能なパスの取得 3. コンタクトの作成 @@ -16,7 +16,7 @@ grpcurl は、コマンドラインツールとしてシンプルなインタフ ```console $ grpcurl -version -grpcurl 1.9.1 +grpcurl 1.9.3 ``` また、通信・認証のための情報は、前節と同様に以下を仮定します。 @@ -27,9 +27,52 @@ grpcurl 1.9.1 本説の説明は、Clover API の最低限の使い方を説明することを目的としているため、より詳しいインタフェースについては API リファレンスに相当する [Protocol Documentation](proto.md) を参照してください。 -## TLE の登録 +## OMM の登録 + +はじめに、衛星の OMM を Clover に登録します。 +OMM（Orbit Mean-Elements Message）は、CCSDS が定義する軌道要素のメッセージ形式です。 +TLE より新しい形式であり、より大きな衛星カタログ番号や詳細な軌道情報を扱えます。 +新しく軌道情報を登録する場合は、基本的に OMM の利用をおすすめします。 + +メソッド `RegisterOMM` にパラメータとして、対象の衛星の ID `satellite_id` と、登録する OMM を渡します。 +現在は KVN（Keyword Value Notation）形式の OMM に対応しているため、`kvn` フィールドに OMM の内容を文字列として指定します。 +ここで、`satellite_id` は仮に 42 とし、OMM には執筆時点の国際宇宙ステーション（ISS）のものを用いることにします。 + +```console +$ grpcurl -cert ./cert.pem -key ./secret.pem \ + -d '{"satellite_id":42,"kvn":"CCSDS_OMM_VERS = 2.0\nOBJECT_NAME = ISS (ZARYA)\nOBJECT_ID = 1998-067A\nCENTER_NAME = EARTH\nREF_FRAME = TEME\nTIME_SYSTEM = UTC\nMEAN_ELEMENT_THEORY = SGP4\nEPOCH = 2024-10-17T04:57:09.000000\nMEAN_MOTION = 15.49966283\nECCENTRICITY = 0.0009135\nINCLINATION = 51.6384\nRA_OF_ASC_NODE = 71.0223\nARG_OF_PERICENTER = 77.3827\nMEAN_ANOMALY = 282.8183\nEPHEMERIS_TYPE = 0\nCLASSIFICATION_TYPE = U\nNORAD_CAT_ID = 25544\nELEMENT_SET_NO = 999\nREV_AT_EPOCH = 47747\nBSTAR = 0.00044173"}' \ + clover.example.com:443 aegs.clover.v1.CloverService/RegisterOMM +``` + +登録した最新の OMM はメソッド `GetLatestOMM` で確認できます。 +取得する OMM の形式は `omm_format` で指定します。現在は `OMM_FORMAT_KVN` に対応しています。 + +```console +$ grpcurl -cert ./cert.pem -key ./secret.pem \ + -d '{"satellite_id":42,"omm_format":"OMM_FORMAT_KVN"}' \ + clover.example.com:443 aegs.clover.v1.CloverService/GetLatestOMM +``` + +OMM が登録できていれば、以下のように登録した OMM が返るはずです。 + +```json +{ + "ommRecord": { + "id": "100", + "kvn": "CCSDS_OMM_VERS = 2.0\nOBJECT_NAME = ISS (ZARYA)\nOBJECT_ID = 1998-067A\nCENTER_NAME = EARTH\nREF_FRAME = TEME\nTIME_SYSTEM = UTC\nMEAN_ELEMENT_THEORY = SGP4\nEPOCH = 2024-10-17T04:57:09.000000\nMEAN_MOTION = 15.49966283\nECCENTRICITY = 0.0009135\nINCLINATION = 51.6384\nRA_OF_ASC_NODE = 71.0223\nARG_OF_PERICENTER = 77.3827\nMEAN_ANOMALY = 282.8183\nEPHEMERIS_TYPE = 0\nCLASSIFICATION_TYPE = U\nNORAD_CAT_ID = 25544\nELEMENT_SET_NO = 999\nREV_AT_EPOCH = 47747\nBSTAR = 0.00044173", + "registerTime": "2026-07-16T08:15:01.874Z" + } +} +``` + +## TLE の登録（互換性のための形式） + +既存のシステムや運用フローとの互換性のため、衛星の TLE も Clover に登録できます。 + +> **TLE の扱いについて** +> +> TLE は互換性のために現在も利用可能な軌道情報の形式であり、Clover では当面の間 Alpha-5 を含む TLE をサポートします。一方で、TLE は固定長の古い形式であり、従来の衛星カタログ番号の範囲は今後枯渇する見込みです。また、表現精度にも制約があります。新しく軌道情報を登録する場合や、より大きなカタログ番号、詳細な軌道情報を扱う場合は、OMM 形式をおすすめします。 -はじめに、衛星の TLE を Clover に登録します。 メソッド `RegisterTLE` にパラメータとして、対象の衛星の ID `satellite_id` と、TLE の各行を `line1`、`line2` のフィールドに分けて渡します。 ここで、`satellite_id` は仮に 42 とし、TLE には執筆時点の国際宇宙ステーション（ISS）のものを用いることにします。 @@ -64,7 +107,7 @@ TLE が登録できていれば、以下のように登録した TLE が返る ## 予約可能なパスの取得 -TLE を登録すれば、各地上局でのパスを取得できるようになります。 +軌道情報を登録すれば、各地上局でのパスを取得できるようになります。 パスの算出には衛星 ID に加えて地上局 ID も必要なため、まず `ListAvailableGroundStations` で利用可能な地上局の ID を調べます: @@ -160,7 +203,7 @@ $ grpcurl -cert ./cert.pem -key ./secret.pem \ コンタクトの `startTime` と `endTime` が引数で渡した AOS/LOS 時刻と異なっていますが、これはコンタクト前後のバッファが加えられたためです。 上記では 5 分となっていますが、この値は場合によって変わる可能性があります。 この `startTime` と `endTime` をもとに、地上局の排他予約が行われます。 -また、コンタクトの予約後に TLE を更新して AOS/LOS 時刻が変化した場合も、コンタクトの開始・終了時刻内で多少の余裕があれば、基本的には問題なく運用できるはずです。 +また、コンタクトの予約後に軌道情報を更新して AOS/LOS 時刻が変化した場合も、コンタクトの開始・終了時刻内で多少の余裕があれば、基本的には問題なく運用できるはずです。 ただし、`status` が `PENDING` の状態では予約は確定していません。 コンタクト作成時の初期状態は `PENDING` で、地上局管理者が承認した場合に `SCHEDULED` に遷移し、そこで予約が確定します。 @@ -168,7 +211,7 @@ $ grpcurl -cert ./cert.pem -key ./secret.pem \ 一度 `REJECTED` になったあと、他の状態に遷移することはありません。 コンタクトの状態は `GetContact` で定期的に確認してください。 -TLE を更新した場合は、最新の AOS/LOS 時刻も確認できます。 +軌道情報を更新した場合は、最新の AOS/LOS 時刻も確認できます。 ```console $ grpcurl -cert ./cert.pem -key ./secret.pem \ From 751b9042544984c84d5ff5650b12cdf9fc4b162a Mon Sep 17 00:00:00 2001 From: sam-ellis Date: Fri, 17 Jul 2026 10:47:22 +0900 Subject: [PATCH 5/5] Updated usage documentation to clarify OMM registration as the recommended flow --- docs/usage.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index f62078cf..33056ee2 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -5,6 +5,7 @@ 1. OMM または TLE（以下、軌道情報）の登録 2. 予約可能なパスの取得 3. コンタクトの作成 +4. コンタクト中のデータの取得 Clover API は [Protocol Buffers](https://protobuf.dev/) で定義されているため、これをもとに各種プログラミング言語のクライアントコードを生成できます。 しかし、ここでは特定のプログラミング言語を用いるのではなく、前節に引き続き [grpcurl](https://github.com/fullstorydev/grpcurl) を用いて説明します。 @@ -31,7 +32,6 @@ grpcurl 1.9.3 はじめに、衛星の OMM を Clover に登録します。 OMM（Orbit Mean-Elements Message）は、CCSDS が定義する軌道要素のメッセージ形式です。 -TLE より新しい形式であり、より大きな衛星カタログ番号や詳細な軌道情報を扱えます。 新しく軌道情報を登録する場合は、基本的に OMM の利用をおすすめします。 メソッド `RegisterOMM` にパラメータとして、対象の衛星の ID `satellite_id` と、登録する OMM を渡します。 @@ -71,7 +71,8 @@ OMM が登録できていれば、以下のように登録した OMM が返る > **TLE の扱いについて** > -> TLE は互換性のために現在も利用可能な軌道情報の形式であり、Clover では当面の間 Alpha-5 を含む TLE をサポートします。一方で、TLE は固定長の古い形式であり、従来の衛星カタログ番号の範囲は今後枯渇する見込みです。また、表現精度にも制約があります。新しく軌道情報を登録する場合や、より大きなカタログ番号、詳細な軌道情報を扱う場合は、OMM 形式をおすすめします。 +> TLE は互換性のために現在も利用可能な軌道情報の形式であり、Clover では当面の間 Alpha-5 を含む TLE をサポートします。 +> 新しく軌道情報を登録する場合は、基本的に OMM 形式をおすすめします。 メソッド `RegisterTLE` にパラメータとして、対象の衛星の ID `satellite_id` と、TLE の各行を `line1`、`line2` のフィールドに分けて渡します。 ここで、`satellite_id` は仮に 42 とし、TLE には執筆時点の国際宇宙ステーション（ISS）のものを用いることにします。 @@ -180,7 +181,7 @@ $ grpcurl -cert ./cert.pem -key ./secret.pem \ ```console $ grpcurl -cert ./cert.pem -key ./secret.pem \ -d '{"satellite_id":42,"ground_station_id":1,"aos":"2024-10-17T18:58:01Z","los":"2024-10-17T19:08:18Z"}' \ - clover.example.com:443 aegs.clover.v1.CloverService/ListPasses + clover.example.com:443 aegs.clover.v1.CloverService/CreateContact ``` コンタクトの作成に成功すると、作成されたコンタクトの情報が返ります。