Arayüz Kataloğu

Bu sayfa tüm arayüzleri işlev grubuna göre listeler. Her konunun öneki lixel/application/ şeklindedir ve tablolarda belirtilmemiştir. Yön işaretleri: REQ=istek, RSP=yanıt, RPT=rapor (bkz. Mesaj Modeli ve Kodek).

Durum İzleme

OpenAPI'nin sunduğu arayüzler arasında yalnızca heartbeat JSON metni kullanır. Cihazı keşfetmek ve protokol sürümünü okumak için kullanılır:

{"DeviceSN":"A256A60000","Timestamp":1697703246.5,"ProtocolVersion":"3.0.0"}

• DeviceSN: cihaz seri numarası.
• Timestamp: cihazın geçerli saati.
• ProtocolVersion: uyumluluk tasarımı için protokol sürümü.

Cihaz durumu saniyede bir bildirilir. Bildirim, haritalama durumunu, sistem kaynaklarını ve RTK durumunu içerir:

message DeviceStatusReport {
    message DeviceStatus {
        sint32 app_sessions = 1; // number of APP sessions
    }
    Header header = 1;
    uint32 modeling_state = 2; // unified status code
    string device_sn = 3;      // device serial number
    string project_id = 4;     // project name
    string time_zone = 5;      // current time zone
    bool init_ready = 6;       // 0: not initialized, 1: initialized
    SystemStatus system_status = 7;
    RtkStatus rtk_status = 8;
    DeviceStatus device_status = 9;
}

Gerçek zamanlı nokta bulutunun ve pozun kodunu çözmek için bkz. Gerçek Zamanlı Veri.

Cihaz Yönetimi

Cihaz kontrolünün desteklediği ActionCmd değerleri: AC_USB_MASS, AC_USB_ETHER, AC_DISK_FORMAT, AC_POWER_OFF, AC_SYSTEM_REBOOT. Ayrıca dosya paylaşımı anahtarları AC_START_FS / AC_STOP_FS desteklenir (bkz. Proje Dosyasına Erişim; etkinleştirildiğinde sabit bir varsayılan kimlik bilgisi kullanılır). AC_DISK_FORMAT, AC_POWER_OFF ve AC_SYSTEM_REBOOT verileri siler veya cihazı kapatır / yeniden başlatır. Çağırmadan önce onay alın.

message DeviceControlRequest {
    Header header = 1;
    Application.ActionCmd action = 2;
}

message DeviceControlResponse {
    Header header = 1;
    Application.ActionCmd action = 2;
    Error error = 15;
}

Cihaz yapılandırması, saatin ve ana depolama türünün ayarlanmasını destekler:

message DeviceConfigRequest {
    message TimeConfig {
        sint64 time_secs = 1; // timestamp (second precision)
        string time_zone = 2; // time zone (e.g. "Asia/Shanghai")
    }
    message MainStorageConfig {
        sint32 storage_type = 1; // 0: internal storage, 1: TF card, 2: USB Disk
    }
    Header header = 1;
    optional TimeConfig time_config = 4;
    optional MainStorageConfig main_storage_config = 8;
}

Tarama ve Haritalama

Tarama action değeri olarak AC_START / AC_STOP desteklenir. AC_START yanıtı yalnızca cihazın isteği aldığı anlamına gelir. Ardından cihaz bekleme → başlatma → tarama durumlarına geçer (ölçümlerde tarama durumuna 14 ila 15 saniye sonra ulaşıldı). Tarama durumuna geçmeden gönderilen AC_STOP ertelenir. Sabit bir süre beklemek yerine report/device_status konusuna abone olun ve modeling_state değerini okuyun. Bkz. Hızlı Başlangıç (Python / C++).

modeling_status, geçerli projenin project_id ve project_name değerlerini, ayrıca poz, kontrol noktası ve ölçüm noktası dosyalarının URL'lerini döndürür. Tarama durumunu döndürmez; bunun için report/device_status içindeki modeling_state değerini kullanın. Cihazda geçerli proje verisi yoksa yanıt yayımlamadan döner. Bekleme modunda yanıt alınmadı (ölçümde 2 zaman aşımı) ve request() TimeoutError hatası verir.

Temel alanlar:

message ModelingRequest {
    Header header = 1;
    Application.ActionCmd action = 2;    // supports AC_START / AC_STOP
    string project_name = 3;             // custom project name
    Modeling.RecordMode record_mode = 4; // RM_CALC / RM_RECORD / RM_RECORD_CALC
    Modeling.ScanMode scan_mode = 5;     // SM_PCL / SM_LCC / SM_PORTRAIT
    Modeling.MountType mount_type = 6;   // MT_HAND / MT_CAR / MT_UAV / MT_BACKPACK
    string pre_project_id = 7;           // preceding project ID (continued-scan feature in later versions)
    Modeling.AssistMode assist_mode = 8; // scan assist mode AM_GUIDED / AM_VISUAL
}

Tarama durumu raporu (report/modeling) kat edilen mesafeyi, hızı, tarama süresini ve tarama sonrası veri işleme ilerlemesini içerir:

message ModelingReport {
    message ScanStatus {
        float move_distance = 1; // travel distance
        float move_speed = 2;    // movement speed
        sint64 scan_time = 3;    // scan time (seconds)
    }
    Header header = 1;
    sint32 pgo_progress = 2; // post-scan data-processing progress (0~100)
    ScanStatus scan_status = 3;
}

Nokta Yönetimi

Kontrol noktası action değeri olarak AC_ADD / AC_REMOVE desteklenir. AC_UPDATE proto içinde tanımlıdır, ancak cihaz bunu işlemez ve EC_ProtoError döndürür (desc değeri invalid action). Ölçüm noktası action değeri yalnızca AC_ADD / AC_REMOVE olarak desteklenir. Aşağıdaki proto bloğundaki yorum, cihaz tarafındaki özgün metni korur ve AC_UPDATE değerinin desteklendiğini belirtir. Bunun yerine buradaki açıklamayı esas alın.

Bekleme modunda cihaz kontrol noktası isteklerine yanıt vermez. Diğer durumlarda yanıt verir (burada yalnızca tarama durumu ölçüldü). Geçerli proje verisi yoksa EC_RequestError döndürür (desc değeri no project data). Ölçümlerde AC_ADD işleminin istekteki id değerini yok saydığı görüldü. Yanıttaki id değerini cihaz belirler ve noktayı kaldırmak için kullanılır. Başarılı bir AC_ADD işleminde error.desc, metin açıklaması değil noktanın pozudur (x y z qw qx qy qz, boşlukla ayrılmış 7 kayan noktalı sayı).

Not: ölçüm noktası özelliği yalnızca bazı cihazlarda desteklenir. Kullanmadan önce hedef cihazınızın bu özelliği sunduğunu doğrulayın.

message ControlPointRequest {
    Header header = 1;
    Application.ActionCmd action = 2; // supports AC_ADD / AC_REMOVE / AC_UPDATE
    sint32 id = 3;                    // control point ID
    sint32 type = 4;                  // type (0: device, 1: centering pole, 100: legacy)
    string label = 5;                 // control point label
    sint32 height = 6;                // base point height (unit: mm)
}

Proje Yönetimi

action şunları destekler:

• AC_LIST_ALL_PROJECTS: tüm projeleri listeler.
• AC_MODIFY_PROJECT_LABELS: etiketleri değiştirir (id + tag_name gerekir).
• AC_DELETE_PROJECTS: projeleri siler (id_list gerekir).

Cihaz tarama başlatırken, tarama yaparken veya taramayı durdururken etiket değiştirme ve proje silme işlemleri reddedilir. Bu işlemleri bekleme modunda yapın. AC_LIST_ALL_PROJECTS işleminin döndürdüğü poses_url, xbin_url vb. değerler HTTP URL'leridir. Ana makine değeri için bkz. Proje Dosyasına Erişim.

message ProjectListRequest {
    Header header = 1;
    // supports AC_LIST_ALL_PROJECTS / AC_MODIFY_PROJECT_LABELS / AC_DELETE_PROJECTS only
    Application.ActionCmd action = 2;
    optional string id = 3;
    optional string tag_name = 4;
    repeated string id_list = 5; // delete multiple projects at once
}

RTK / Ntrip

• Ntrip ayarlama action değeri olarak AC_LOGIN / AC_LOGOUT desteklenir.
• CORS türü: CUSTOM / QIANXUN / ZHONGYI.
• Koordinat sistemi: UNKNOWN / ITRF2008 / WGS84 / CGCS2000.
• RTK uydu sistemleri: GPS / BDS / GLO / GAL / QZSS / IRNSS.

Not: RTK donanımı bağlı değilse (RtkStatus.state değeri HwDisconnected) veya RTK cihazı yoksa Ntrip ayarlama isteği reddedilir ve cihaz EC_RequestError döndürür (desc değeri operation forbidden). Ayrıca, cihazın Wi-Fi bağlantısı AP modundayken (Ntrip verisi WebSocket üzerinden iletilir) yanıtın, yok sayılabilecek bilinmeyen bir hata kodu döndürdüğüne ve cihazın Ntrip bağlantısının bu durumdan etkilenmediğine dair bir kayıt vardır. Cihaz tarafı kaynak kodunda buna karşılık gelen bir işleme rastlanmadı, bu nedenle bu bilgi doğrulanmamıştır.

Veri İşleme

data_source şu anda XBIN_DATA değerini destekler. data_topics belirtilmezse her şey açılır. report/data_unpack paket açma ilerlemesini bildirir (0~100). Cihaz bekleme modunda değilse bu istek EC_RequestError döndürür.

message DataUnpackRequest {
    enum DataSource {
        XBIN_DATA = 0; // xbin data
    }
    Header header = 1;
    string project_name = 2;           // project name
    DataSource data_source = 3;        // data source
    repeated string data_topics = 4;   // data topics (unpack all by default if omitted)
    optional string data_ouputdir = 5; // output directory name (relative to the project directory)
}

Not: Veri açma (unpack) özelliği yalnızca belirli modellerde ve firmware sürümlerinde desteklenir. Kullanmadan önce firmware sürümünü heartbeat mesajındaki ProtocolVersion alanından veya cihaz bilgisinden sorgulayın. Ardından hedef model / firmware sürümünün bu özelliği destekleyip desteklemediğini XGRIDS ile doğrulayın. Desteklenmeyen bir cihazda istek hiçbir etki yapmaz.

Hata Kodu Kuralı

İstek-yanıt mesajları sonucu Error error = 15 alanında taşır. Yaygın olanlar: EC_RequestSuccess, EC_RequestError, EC_ProtoError. Ntrip ile ilgili olanlar: EC_NtripLoginSuccess, EC_NtripLogoutSuccess, EC_NtripLogoutFailed, EC_NtripDisConnected, EC_NtripNetworkError, EC_NtripAuthError. Tam liste için Hata Kodları sayfasına bakın.