# Zyfra Robot Drill Telemetry

## Telemetry

### Telemetry source
- The source of the telemetry data comes from the drill **onboard** system. This system collects various measurements about the drilling process, such as drill rotation speed, drill rotation pressure, air pressure, spindle depth, drill feed speed, and drill feed pressure.
- **HAL** receives the telemetry data from the Drill Onboard system and then publishes it using the /metrics endpoint.
- **Prometheus** is a monitoring and alerting toolkit that gathers the telemetry data published by HAL. It collects and stores the data in a time-series format, allowing for efficient querying and analysis of the telemetry data over time.

### Metrics

Metrics:

- `main_mode`: Represents the current main mode of the vehicle, which includes various modes like idle, moving, wait_before_level, leveling, wait_after_level, tower_tilt, drilling, grounding, restore_string, failure, remote_wait, remote_prepare, remote, and end_remote.
- `platform_roll`: Represents the roll angle of the platform.
- `platform_pitch`: Represents the pitch angle of the platform.
- `tower_angle`: Represents the angle of the tower during the drilling process.
- `speed`: Represents the speed of the drill.
- `drill_angular_pose`: Represents the angular pose of the drill (yaw).
- `spindle_depth`: Represents the depth of the spindle in the drilling process.
- `drill_rotation_speed`: Represents the rotation speed of the drill during the drilling process.
- `drill_feed_speed`: Represents the feed speed of the drill during the drilling process.
- `drill_rotation_pressure`: Represents the rotation pressure of the drill during the drilling process.
- `drill_feed_pressure`: Represents the feed pressure of the drill during the drilling process.
- `air_pressure`: Represents the air pressure during the drilling process.

Each metric is associated with a specific `hole_id` and `vehicle_id`, allowing you to filter and analyze the data based on individual drilling operations and equipment.

## Querying the telemetry data

You can directly connect to the Prometheus server to query the telemetry data with PromQL.
Alternatively, you can use the REST API provided by the system to get the current telemetry data or the telemetry data for a specified hole.
This API allows you to filter the data based on specific fields and select a sampling period for the time-series data.

### REST API for Telemetry

| Address | Method | Description | Request Body Example (JSON) | Response Body Example (JSON) |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
| /api/vehicles/telemetry | GET | Handles the GET request to obtain _current_ telemetry data for all vehicles in a map format, where keys represent vehicle IDs and values represent maps with telemetry data. | | See "Telemetry" structure example |
| /api/vehicles/{vehid}/telemetry | GET | Handles the GET request to obtain _current_ telemetry data for a specific vehicle by its ID. | | See "Telemetry" structure example |
| /api/telemetry | POST | Handles the GET request to obtain all telemetry values and corresponding timestamps (time series) for the specified hole (task). The request body contains the names of telemetry fields of interest to the client, the time step, and the target hole ID. | ```{"hole_id": 113, "frequency": 0.5, "fields": ["drill_rotation_pressure", "air_pressure"]}```<br/> You could get hole ids from history REST route, check [rest.md](./rest.md) for details, make a distinction between hale name and id. | See "Hole Telemetry (time series)" structure example |

Check [telemetry_download.py](../../src/utils/telemetry/telemetry_download.py) script as an example of the usage of an API to retrieve telemetry data for drilled holes.

# Telemetry structure example

{
   "2":{
      "veh_polygon":[
         {
            "y":-1.54,
            "x":6.11
         },
         {
            "y":-1.54,
            "x":2.66
         },
         {
            "y":-2.13,
            "x":2.06
         },
         {
            "y":-2.13,
            "x":-5.71
         },
         {
            "y":2.13,
            "x":-5.71
         },
         {
            "y":2.13,
            "x":1.42
         },
         {
            "y":3.5,
            "x":1.42
         },
         {
            "y":3.5,
            "x":6.11
         }
      ],
      "tower_height":19.963060379,
      "tower_angle":0.00425554346293211,
      "driller_status":"failure",
      "rear_jack_pulled":true,
      "platform_roll":-0.00035520701203495264,
      "drill_rotation_pressure":0.0,
      "drill_rotation_speed":0.0,
      "drill_angular_pose":0.0,
      "platform_pitch":0.5162708163261414,
      "spindle_depth":1.2166346311569214,
      "position":{
         "y":-4.787239475790718,
         "x":3.6634759322085846,
         "z":4251.993238639921,
         "azimuth":-12.510881423950195
      },
      "right_jack_pulled":true,
      "air_pressure":0.0,
      "drill_feed_pressure":0.0,
      "left_jack_pulled":true,
      "string_len":18.86773771,
      "speed":-8.1178943219129e-05,
      "drill_feed_speed":5.902282282477245e-05,
      "last_finished_holeid":"230"
   }
}

### Test REST Request for Hole Telemetry with _curl_

curl -X POST -H "Content-Type: application/json" -d '{
    "hole_id": 1040,
    "period": 20,
    "fields": [
        "drill_rotation_speed",
        "drill_rotation_pressure",
        "air_pressure",
        "spindle_depth",
        "drill_feed_speed",
        "drill_feed_pressure"
    ]
}' 'http://127.0.0.1:8083/api/telemetry'

Result example:

{
    "metrics": {
        "air_pressure": {
            "time_series": [
                [
                    1678197766.0,
                    0.0
                ],
                [
                    1678197786.0,
                    0.0
                ],
                ...
                [
                    1678198246.0,
                    0.0
                ]
            ]
        },
        "drill_feed_pressure": {
            "time_series": [
                [
                    1678197766.0,
                    0.0
                ],
                [
                    1678197786.0,
                    0.0
                ],
                ...
                [
                    1678198246.0,
                    0.0
                ]
            ]
        },
        "drill_feed_speed": {
            "time_series": [
                [
                    1678197766.0,
                    1.2160908272011644e-17
                ],
                [
                    1678197786.0,
                    5.812536125864184e-18
                ],
                ...
                [
                    1678198246.0,
                    0.0014401712687686086
                ]
            ]
        },
        "drill_rotation_pressure": {
            "time_series": [
                [
                    1678197766.0,
                    0.0
                ],
                [
                    1678197786.0,
                    0.0
                ],
                ...
                [
                    1678198246.0,
                    0.0
                ]
            ]
        },
        "drill_rotation_speed": {
            "time_series": [
                [
                    1678197766.0,
                    0.0
                ],
                [
                    1678197786.0,
                    0.0
                ],
                ...
                [
                    1678198246.0,
                    0.0
                ]
            ]
        },
        "spindle_depth": {
            "time_series": [
                [
                    1678197766.0,
                    1.2323776483535767
                ],
                [
                    1678197786.0,
                    1.2323776483535767
                ],
                ...
                [
                    1678198246.0,
                    1.218726634979248
                ]
            ]
        }
    },
    "vehicle_id": "2"
}

#### CSV

curl -X POST -H "Content-Type: application/json" -d '{
    "hole_id": 1439,
    "period": 20,
    "fields": [
        "drill_rotation_speed",
        "drill_rotation_pressure",
        "air_pressure",
        "spindle_depth",
        "drill_feed_speed",
        "drill_feed_pressure"
    ],
    "format": "csv"
}' 'http://127.0.0.1:8083/api/telemetry'

Result

timestamp,air_pressure,drill_feed_pressure,drill_feed_speed,drill_rotation_pressure,drill_rotation_speed,spindle_depth
1681231236.0,0.0,0.0,1.2439296734346978e-17,0.0,0.0,1.2112303972244263
1681231256.0,0.0,0.0,5.8670444330992846e-18,0.0,0.0,1.2112303972244263
1681231276.0,0.0,0.0,3.837855412401563e-18,0.0,0.0,1.2112303972244263
1681231296.0,0.0,0.0,2.85186377365902e-18,0.0,0.0,1.2112303972244263
1681231316.0,0.0,0.0,2.2690095665873114e-18,0.0,0.0,1.2112303972244263
1681231336.0,0.0,0.0,1.8839743622367407e-18,0.0,0.0,1.2112303972244263
1681231356.0,0.0,0.0,1.6106599291763835e-18,0.0,0.0,1.2112303972244263
1681231376.0,0.0,0.0,1.4065909565419482e-18,0.0,0.0,1.2112303972244263
1681231396.0,0.0,0.012611049227416515,0.2056780606508255,0.0,0.0,2.212783098220825
1681231416.0,2.8414180278778076,35.52585983276367,0.014852846972644329,41.674076080322266,56.39613342285156,3.332256555557251
1681231436.0,2.848191976547241,50.00687026977539,0.01908353716135025,49.894615173339844,57.030921936035156,3.6859211921691895
1681231456.0,2.8461711406707764,116.30227661132812,0.03427360951900482,118.08776092529297,79.62208557128906,4.2386345863342285
1681231476.0,2.86295747756958,139.5303192138672,0.032050684094429016,136.6859130859375,79.99544525146484,5.005785942077637
1681231496.0,2.8389923572540283,154.79396057128906,0.03508607670664787,147.22117614746094,79.99551391601562,5.62611722946167
<...>
1681231896.0,2.842348337173462,0.03958992287516594,-0.7099394202232361,24.54488754272461,60.10071563720703,14.351974487304688
1681231916.0,0.0,0.0,-0.1692872792482376,0.0,0.0647430568933487,2.16379976272583
1681231936.0,0.0,0.0,1.560186137794517e-05,0.0,0.0,1.2177925109863281

### Test Prometheus PromQL Request with _curl_

curl -G 'http://127.0.0.1:9090/api/v1/query_range' \
--data-urlencode 'query={__name__=~"drill_rotation_speed|drill_rotation_pressure|air_pressure|spindle_depth|drill_feed_speed|drill_feed_pressure"}' \
--data-urlencode "start=$start" \
--data-urlencode "end=$end" \
--data-urlencode 'step=5s'

Or with parameters (hole_id)

curl -G 'http://127.0.0.1:9090/api/v1/query_range' \
--data-urlencode 'query={__name__=~"drill_rotation_speed|drill_rotation_pressure|air_pressure|spindle_depth|drill_feed_speed|drill_feed_pressure", hole_id="166"}' \
--data-urlencode "start=$start" \
--data-urlencode "end=$end" \
--data-urlencode 'step=5s'

Result example:

{
    "status": "success",
    "data": {
        "resultType": "matrix",
        "result": [
            {
                "metric": {
                    "__name__": "air_pressure",
                    "hole_id": "166",
                    "instance": "rest:80",
                    "job": "rest",
                    "vehicle_id": "2"
                },
                "values": [
                    [
                        1680777117,
                        "0"
                    ],
                    [
                        1680777122,
                        "0"
                    ],
                    ...
                    [
                        1680777602,
                        "0"
                    ]
                ]
            },
            {
                "metric": {
                    "__name__": "drill_feed_pressure",
                    "hole_id": "166",
                    "instance": "rest:80",
                    "job": "rest",
                    "vehicle_id": "2"
                },
                "values": [
                    [
                        1680777117,
                        "0"
                    ],
                    [
                        1680777122,
                        "0"
                    ],
                    ...
                    [
                        1680777602,
                        "0"
                    ]
                ]
            },
            {
                "metric": {
                    "__name__": "drill_feed_speed",
                    "hole_id": "166",
                    "instance": "rest:80",
                    "job": "rest",
                    "vehicle_id": "2"
                },
                "values": [
                    [
                        1680777117,
                        "1.186873932468302e-10"
                    ],
                    [
                        1680777122,
                        "2.8438042766725912e-15"
                    ],
                    ...
                    [
                        1680777602,
                        "1.034417995704473e-09"
                    ]
                ]
            },
            {
                "metric": {
                    "__name__": "drill_rotation_pressure",
                    "hole_id": "166",
                    "instance": "rest:80",
                    "job": "rest",
                    "vehicle_id": "2"
                },
                "values": [
                    [
                        1680777117,
                        "0"
                    ],
                    [
                        1680777122,
                        "0"
                    ],
                    ...
                    [
                        1680777602,
                        "0"
                    ]
                ]
            },
            {
                "metric": {
                    "__name__": "drill_rotation_speed",
                    "hole_id": "166",
                    "instance": "rest:80",
                    "job": "rest",
                    "vehicle_id": "2"
                },
                "values": [
                    [
                        1680777117,
                        "0"
                    ],
                    [
                        1680777122,
                        "0"
                    ],
                    ...
                    [
                        1680777602,
                        "0"
                    ]
                ]
            },
            {
                "metric": {
                    "__name__": "spindle_depth",
                    "hole_id": "166",
                    "instance": "rest:80",
                    "job": "rest",
                    "vehicle_id": "2"
                },
                "values": [
                    [
                        1680777117,
                        "1.2331069707870483"
                    ],
                    [
                        1680777122,
                        "1.2331069707870483"
                    ],
                    ...
                    [
                        1680777602,
                        "1.236752986907959"
                    ]
                ]
            }
        ]
    }
}

### Get a List of All Metrics and Types with _curl_

curl -s 'http://localhost:9090/api/v1/label/__name__/values' | jq '.data[]' | xargs -I {} sh -c "curl -s 'http://localhost:9090/api/v1/metadata?metric={}' | jq '.data.\"{}\" | {metric: \"{}\", type: .[0].type}'"

Result example:

{
  "metric": "air_pressure",
  "type": "gauge"
}
{
  "metric": "drill_angular_pose",
  "type": "gauge"
}
{
  "metric": "drill_feed_pressure",
  "type": "gauge"
}
{
  "metric": "drill_feed_speed",
  "type": "gauge"
}
{
  "metric": "drill_rotation_pressure",
  "type": "gauge"
}
{
  "metric": "drill_rotation_speed",
  "type": "gauge"
}
{
  "metric": "main_mode",
  "type": "stateset"
}
{
  "metric": "platform_pitch",
  "type": "gauge"
}
{
  "metric": "platform_roll",
  "type": "gauge"
}
{
  "metric": "scrape_duration_seconds",
  "type": null
}
{
  "metric": "scrape_samples_post_metric_relabeling",
  "type": null
}
{
  "metric": "scrape_samples_scraped",
  "type": null
}
{
  "metric": "scrape_series_added",
  "type": null
}
{
  "metric": "speed",
  "type": "gauge"
}
{
  "metric": "spindle_depth",
  "type": "gauge"
}
{
  "metric": "tower_angle",
  "type": "gauge"
}
{
  "metric": "up",
  "type": null
}
'''