Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion compose.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ services:

openc3-tsdb:
image: "${OPENC3_REGISTRY}/${OPENC3_NAMESPACE}/openc3-tsdb${OPENC3_IMAGE_SUFFIX}:${OPENC3_TAG}"
platform: "${OPENC3_TSDB_PLATFORM:-linux/amd64}"
platform: "${OPENC3_TSDB_PLATFORM}"
# ports:
# # This gives complete access to the QuestDB instance, which is useful for testing and development.
# - "127.0.0.1:9000:9000" # OPENC3_TSDB_INGEST_PORT & QuestDB Console
Expand Down
42 changes: 8 additions & 34 deletions docs.openc3.com/docs/configuration/_conversions.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,6 @@ from openc3.conversions.conversion import Conversion
# Custom conversion class
# See https://docs.openc3.com/docs/configuration/telemetry#read_conversion
class DoubleConversion(Conversion):
def __init__(self):
super().__init__()
# Should be one of 'INT', 'UINT', 'FLOAT', 'STRING', 'BLOCK', 'BOOL', 'ARRAY', 'OBJECT', 'ANY', 'TIME'
self.converted_type = 'STRING'
# Size of the converted type in bits
# Use 0 for 'STRING' or 'BLOCK' where the size can be variable
self.converted_bit_size = 0

# @param value [Object] Value based on the item definition. This could be
# a string, integer, float, or array of values.
# @param packet [Packet] The packet object where the conversion is defined
Expand All @@ -61,23 +53,7 @@ class DoubleConversion(Conversion):
return value
```

There are a lot of comments to help you know what to do. The primary things to modify are the `converted_type`, `converted_bit_size`, and `call` method.

### converted_type

The `converted_type` is the resulting type of the converted value. It lets consumers of the converted value know the resulting type. In our case we're doubling the input value and since this could be applied to an unsigned integer as well as a floating point value we'll choose `FLOAT`.

```python
self.converted_type = 'FLOAT'
```

### converted_bit_size

The `converted_bit_size` is the resulting size of the converted value. It lets consumers of the converted value know the resulting size. Since we chose `FLOAT` as the type we'll choose `32` as the bit size. We could have also chosen `64` bits. Sometimes you know the type and size of the resulting conversion and can simply hard code them. Other times you need to pass them in as parameters and let the user decide.

```python
self.converted_bit_size = 32
```
There are a lot of comments to help you implement the `call` method.

### call

Expand All @@ -86,24 +62,20 @@ The call method is where the actual conversion logic is implemented. In our case
```python
from openc3.conversions.conversion import Conversion
class DoubleConversion(Conversion):
def __init__(self):
super().__init__()
self.converted_type = 'FLOAT'
self.converted_bit_size = 32

def call(self, value, packet, buffer):
return value * 2
```

### Apply Conversion

Now that we have implemented the conversion logic we need to apply it to a telemetry item by adding the line `READ_CONVERSION double_conversion.py` in the [telemetry](/docs/configuration/telemetry) definition file. This could look something like this:
Now that we have implemented the conversion logic we need to apply it to a telemetry item by adding the line `READ_CONVERSION double_conversion.py` in the [telemetry](/docs/configuration/telemetry) definition file. We also apply a `CONVERTED_DATA` keyword to indicate we're changing the data type.

```bash
TELEMETRY GSE DATA BIG_ENDIAN "Data packet"
... # Header items
APPEND_ITEM VALUE 16 UINT "Value I want to double"
READ_CONVERSION double_conversion.py
CONVERTED_DATA 32 FLOAT
```

# Built-in Conversions
Expand All @@ -112,7 +84,7 @@ TELEMETRY GSE DATA BIG_ENDIAN "Data packet"

**Applies a simple conversion to a single telemetry item.**

The generic conversion is meant to be a quick and easy way to apply a conversion to a single telemetry item. It must be parsed and evaluated and thus is not as performant as a dedicated conversion class.
The generic conversion is meant to be a quick and easy way to apply a conversion to a single telemetry item. It must be parsed and evaluated and thus is not as performant as a dedicated conversion class. To specify the bit size, type, and array size of the converted data, use the CONVERTED_DATA keyword.

| Parameter | Description | Required |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
Expand All @@ -123,18 +95,20 @@ The generic conversion is meant to be a quick and easy way to apply a conversion
<TabItem value="python" label="Python">

```python
GENERIC_READ_CONVERSION_START FLOAT 32
GENERIC_READ_CONVERSION_START
packet.read('TEMP1') / 1_000_000
GENERIC_READ_CONVERSION_END
CONVERTED_DATA 32 FLOAT
```

</TabItem>
<TabItem value="ruby" label="Ruby">

```ruby
GENERIC_READ_CONVERSION_START FLOAT 32
GENERIC_READ_CONVERSION_START
packet.read('TEMP1') / 1_000_000
GENERIC_READ_CONVERSION_END
CONVERTED_DATA 32 FLOAT
```

</TabItem>
Expand Down
6 changes: 4 additions & 2 deletions docs.openc3.com/docs/configuration/_telemetry.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,12 +131,14 @@ TELEMETRY TARGET HS BIG_ENDIAN "Health and Status for My Target"
STATE NORMAL 0 GREEN
STATE DIAG 1 YELLOW
ITEM TIMESECONDS 0 0 DERIVED "DERIVED TIME SINCE EPOCH IN SECONDS"
GENERIC_READ_CONVERSION_START FLOAT 32
GENERIC_READ_CONVERSION_START
((packet.read('ccsdsday') * 86400.0) + (packet.read('ccsdsmsod') / 1000.0) + (packet.read('ccsdsusoms') / 1000000.0) )
GENERIC_READ_CONVERSION_END
CONVERTED_DATA 32 FLOAT
ITEM TIMEFORMATTED 0 0 DERIVED "DERIVED TIME SINCE EPOCH AS A FORMATTED STRING"
GENERIC_READ_CONVERSION_START STRING 216
GENERIC_READ_CONVERSION_START
time = Time.ccsds2mdy(packet.read('ccsdsday'), packet.read('ccsdsmsod'), packet.read('ccsdsusoms'))
sprintf('%04u/%02u/%02u %02u:%02u:%02u.%06u', time[0], time[1], time[2], time[3], time[4], time[5], time[6])
GENERIC_READ_CONVERSION_END
CONVERTED_DATA 216 STRING
```
7 changes: 4 additions & 3 deletions docs.openc3.com/docs/configuration/accessors.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ TELEMETRY CBOR CBORTLM BIG_ENDIAN "CBOR Accessor Telemetry"
KEY $.id_item
APPEND_ITEM ITEM1 16 UINT "Int Item 2"
KEY $.item1
GENERIC_READ_CONVERSION_START UINT 16
GENERIC_READ_CONVERSION_START
value * 2
GENERIC_READ_CONVERSION_END
UNITS CELSIUS C
Expand Down Expand Up @@ -207,6 +207,7 @@ COMMAND HTML SEARCH BIG_ENDIAN "Searches Rubygems.org"
GENERIC_READ_CONVERSION_START
value.split.join('+')
GENERIC_READ_CONVERSION_END
CONVERTED_DATA 0 STRING
# This sets header Content-Type=text/html
# Note that TYPE is not used since the KEY is specified
PARAMETER HTTP_HEADER_TYPE 0 0 DERIVED nil nil "text/html"
Expand Down Expand Up @@ -281,7 +282,7 @@ TELEMETRY JSON JSONTLM BIG_ENDIAN "JSON Accessor Telemetry"
KEY $.id_item
APPEND_ITEM ITEM1 16 UINT "Int Item 2"
KEY $.item1
GENERIC_READ_CONVERSION_START UINT 16
GENERIC_READ_CONVERSION_START
value * 2
GENERIC_READ_CONVERSION_END
UNITS CELSIUS C
Expand Down Expand Up @@ -376,7 +377,7 @@ TELEMETRY XML XMLTLM BIG_ENDIAN "XML Accessor Telemetry"
KEY "/html/head/script/@src"
APPEND_ITEM ITEM1 16 UINT "Int Item 2"
KEY "/html/head/noscript/text()"
GENERIC_READ_CONVERSION_START UINT 16
GENERIC_READ_CONVERSION_START
value * 2
GENERIC_READ_CONVERSION_END
UNITS CELSIUS C
Expand Down
2 changes: 1 addition & 1 deletion docs.openc3.com/docs/development/streaming-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -286,7 +286,7 @@ class StreamingObject
attr_reader :target_name # String: target name, e.g. "INST"
attr_reader :packet_name # String: packet name, e.g. "ADCS"
attr_reader :item_name # String or nil: item name (nil for whole packets)
attr_reader :value_type # Symbol: :RAW, :CONVERTED, :FORMATTED, :WITH_UNITS, :PURE
attr_reader :value_type # Symbol: :RAW, :CONVERTED, :FORMATTED, :PURE
attr_reader :reduced_type # Symbol or nil: :MIN, :MAX, :AVG, :STDDEV (reduced modes only)
attr_accessor :start_time # Integer or nil: nanoseconds from epoch
attr_accessor :end_time # Integer or nil: nanoseconds from epoch
Expand Down
32 changes: 17 additions & 15 deletions docs.openc3.com/docs/guides/scripting-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,8 @@ The following API methods have been removed from COSMOS v7. Since WITH_UNITS wer
| wait_tolerance_raw | api_shared | Removed, use [wait_tolerance](#wait_tolerance) and pass type |
| wait_check_tolerance_raw | api_shared | Removed, use [wait_check_tolerancet](#wait_check_tolerance) and pass type |

The following API methods now return `COSMOS__CANCEL` instead of `Cancel` when the Cancel button is pushed in Script Runner: `ask`, `ask_string`, `message_box`, `vertical_message_box`, `combo_box`, `check_box`, `prompt`, `prompt_for_hazardous`, `prompt_for_critical_cmd`, `metadata_input`, `open_file_dialog`, `open_files_dialog`, `open_bucket_dialog`. Unless you are _explicitly_ checking the return value for the word 'Cancel' there are no changes required.

### Migration from COSMOS v5 to v6

See the [Migrating From COSMOS 5 to COSMOS 6](../getting-started/upgrading#migrating-from-cosmos-5-to-cosmos-6) guide for other changes including migrating to Vue 3 and Vuetify 3.
Expand Down Expand Up @@ -8962,25 +8964,25 @@ create_timeline_activity(name, kind, start, stop, data={})
</TabItem>
</Tabs>

| Parameter | Description |
| --------- | ----------------------------------------------------------------------------- |
| name | Name of the timeline |
| kind | Type of the activity. One of COMMAND, SCRIPT, or RESERVE. |
| start | Start time of the activity. Time / datetime instance. |
| stop | Stop time of the activity. Time / datetime instance. |
| Parameter | Description |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | Name of the timeline |
| kind | Type of the activity. One of COMMAND, SCRIPT, or RESERVE. |
| start | Start time of the activity. Time / datetime instance. |
| stop | Stop time of the activity. Time / datetime instance. |
| data | Hash / dict of data for COMMAND or SCRIPT type. Default is empty hash / dict. Valid keys are described [below](#create_timeline_activity-data-parameter). |
| scope | Scope of the activity. Default is the OPENC3_SCOPE, usually "DEFAULT". |
| scope | Scope of the activity. Default is the OPENC3_SCOPE, usually "DEFAULT". |

#### create_timeline_activity data parameter
| Key | Value |
|-----|-------|
| username | Username to display as the creator of the activity. Default is "operator". |
| customTitle | Custom title to display for the activity. Default is empty string which results in no custom title being shown. |
| notes | Notes to display for the activity. Default is empty string, which results in no notes being shown. |
| command | Command to execute for COMMAND type activities. |
| script | Script to execute for SCRIPT type activities. Should be given as the path to the script file to run, starting with the target name, e.g. "INST/procedures/collect.rb". |
| environment | Array of environment variable key/value pairs to set for SCRIPT type activities, e.g. `[{key: "USER", value: "JASON"}]` |

| Key | Value |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username | Username to display as the creator of the activity. Default is "operator". |
| customTitle | Custom title to display for the activity. Default is empty string which results in no custom title being shown. |
| notes | Notes to display for the activity. Default is empty string, which results in no notes being shown. |
| command | Command to execute for COMMAND type activities. |
| script | Script to execute for SCRIPT type activities. Should be given as the path to the script file to run, starting with the target name, e.g. "INST/procedures/collect.rb". |
| environment | Array of environment variable key/value pairs to set for SCRIPT type activities, e.g. `[{key: "USER", value: "JASON"}]` |

<Tabs groupId="script-language">
<TabItem value="ruby" label="Ruby Example">
Expand Down
Loading
Loading