adding COSMOS instructions to Pico readme

src/assembly/pico/main/README.md

@@ -118,6 +118,130 @@ You can verify that telemetry is being produced by the Pico by opening the USB s
 $ screen /dev/tty.usbserial-230 115200
 ```
 
+## Commanding and Telemetry with OpenC3 [COSMOS](https://github.com/OpenC3/cosmos)
+
+ ![`Commanding and Telemetry with OpenC3 COSMOS`](img/cosmos.png "Commanding and Telemetry with OpenC3 COSMOS")
+
+To best interact with the Linux assembly, we need to use a ground system interface, such as OpenC3 COSMOS. To install COSMOS, navigate to an appropriate directory on your host machine and clone the COSMOS example project repository:
+
+```
+$ git clone https://github.com/openc3/cosmos-project.git
+```
+
+The COSMOS Docker container must be configured to use the same serial ports as Adamant. Edit this configuration at `cosmos-project/compose.yaml` and add the following entry to the `openc3-operator:` section:
+
+```
+    devices:
+      - /dev/ttyACM0:/dev/tty0
+```
+
+Note that the device name may vary between systems and should correspond to the device file for the Pico's USB port. To find the device file for your USB port, use the following command:
+
+```
+$ ls /dev/tty*
+```
+
+Start COSMOS by running:
+
+```
+$ cd cosmos-project
+$ ./openc3.sh start
+```
+
+After the containers start, open a web browser and navigate to `http://localhost:2900`. You will be prompted to configure a password, and then presented with the COSMOS interface. Some modules may still be loading, but after a minute the interface should be complete. Navigate to `ADMIN CONSOLE` and uninstall the "openc3-cosmos-demo" plugin by selecting the `Delete Plugin` icon.
+
+OpenC3 COSMOS runs inside of its own Docker containers. The COSMOS example project provides the necessary tools and commands to create an interface plugin from our generated configuration files. While still in the `cosmos-project` directory, run:
+
+```
+$ ./openc3.sh cli generate plugin PICO_EXAMPLE
+```
+
+This creates a new directory called `openc3-cosmos-pico-example`. Next, run:
+
+```
+$ cd openc3-cosmos-pico-example
+$ ../openc3.sh cli generate target PICO_EXAMPLE
+```
+
+This creates the plugin directory structure as well as template configuration files that our generated configuration will replace. These files are located at:
+
+```
+cosmos-project/openc3-cosmos-pico-example/plugin.txt
+cosmos-project/openc3-cosmos-pico-example/targets/PICO_EXAMPLE/cmd_tlm/cmd.txt
+cosmos-project/openc3-cosmos-pico-example/targets/PICO_EXAMPLE/cmd_tlm/tlm.txt
+```
+
+After installing and running COSMOS we need to build the Pico Example plugin configuration files. This will allow COSMOS to decode telemetry from the Adamant virtual environment and properly format outgoing commands.
+
+These files are autocoded by Adamant. From the Adamant virtual environment run:
+
+```
+$ cd adamant_example/src/assembly/pico/main
+$ redo cosmos_config
+```
+
+This generates the plugin configuration file and its respective command and telemetry configurations in the `adamant_example/src/assembly/pico/build/cosmos/plugin/` directory. The plugin configuration template file is located in the `adamant_example/src/assembly/pico/build/cosmos/template/` directory, and should be reviewed to ensure the interface and required protocols are correct. By default, this template applies settings specific to the Linux example using TCP, and should be modified for the serial connection used by the Pico. The Adamant template includes a serial configuration in comments, and after review this should resemble:
+
+```
+# COSMOS interface documentation is available at: https://docs.openc3.com/docs/configuration/interfaces
+# Set variables here to allow variation in your plugin.
+# Variables are able to be modified at time of install in COSMOS.
+Variable linux_example_target_name Pico_Example
+Variable crc_parameter_name CRC
+Variable checksum_parameter_name Checksum
+# If TCP:
+# Variable port_w 2003
+# Variable port_r 2003
+# If serial:
+Variable port_w /dev/ttyACM0
+Variable port_r /dev/ttyACM0
+
+Target Linux_Example <%= linux_example_target_name %>
+# TCP example interface:
+# Interface <%= linux_example_target_name %>_INT tcpip_server_interface.rb <%= port_w %> <%= port_r %> 10.0 nil Length 32 16 7
+#   Map_Target <%= linux_example_target_name %>
+#   Protocol Read crc_protocol.rb <%= crc_parameter_name %> false "ERROR" -16 16
+#   Protocol Write cmd_checksum.rb <%= checksum_parameter_name %>
+# Serial example interface:
+Interface <%= linux_example_target_name %>_INT serial_interface.rb <%= port_w %> <%= port_r %> 10.0 nil Length 64 16 11 1 Big_Endian 0 FED4AFEE
+  Map_Target <%= linux_example_target_name %>
+  Protocol Read crc_sync_protocol.rb <%= crc_parameter_name %> false "ERROR" -16 16
+  Protocol Write cmd_sync_checksum.rb <%= checksum_parameter_name %>
+```
+
+A helper script, which takes the relative paths to the Adamant assembly yaml file and COSMOS install directory as arguments, is provided to copy the plugin configuration files, and any custom protocols used by the configuration, to the correct directories. If the COSMOS and Adamant example project directories are adjacent, complete the configuration by running:
+
+```
+$ cd adamant_example/gnd/cosmos
+$ ./install_cosmos_plugin.sh ../../src/assembly/pico/pico_example.assembly.yaml ../../../cosmos-project
+```
+
+The plugin can now be compiled. Next, run:
+
+```
+$ cd cosmos-project/openc3-cosmos-pico-example
+$ ../openc3.sh cli rake build VERSION=1.0.0
+```
+
+Select `Click to select plugin .gem file to install` and navigate to the compiled plugin gem file at `cosmos-project/openc3-cosmos-pico-example/openc3-cosmos-pico-example-1.0.0.gem` to install our generated plugin. The plugin is templated to allow changing of parameters such as serial ports, but the default values are already set to correspond with this project.
+
+The plugin will be installed. With the Pico connected and running, the COSMOS Log Messages panel should show that the serial interface has accepted a new connection from Adamant.
+
+With COSMOS running, here are some interesting things you can try:
+
+ 1. View messages generated from the Linux assembly in the main panel.
+ 2. View telemetry from the Counter and Oscillator components by opening the `Telemetry Grapher` panel and selecting the "PICO_EXAMPLE" target, "HOUSEKEEPING_PACKET" packet, "OSCILLATOR_A.OSCILLATOR_VALUE.VALUE" as item, and selecting "Add Item".
+ 3. Send any command by selecting it in the `Command Sender` panel. Try sending a NOOP or changing the Oscillator frequencies by selecting "Oscillator_A-Set_Frequency", changing "Value", and selecting "Send".
+ 4. View the queue usage for each component by opening the `Packet Viewer` panel and selecting "HOUSEKEEPING_PACKET".
+ 5. Send an interrupt to the running assembly by running `sh send_interrupt.sh` from within another terminal in the Adamant virtual environment.
+
+```
+$ cd adamant_example/src/assembly/pico/main
+$ sh send_interrupt.sh
+```
+
+You should see the software respond by printing out `Interrupt received` with a time stamp in the terminal where `redo run` was started.
+
 ## Commanding and Telemetry with Hydra
 
  ![`Commanding and Telemetry with Hydra`](img/hydra.jpg "Commanding and Telemetry with Hydra")

src/assembly/pico/main/cosmos_config.do

@@ -0,0 +1,6 @@
+# Create Cosmos plugin configuration files:
+export TARGET=
+this_dir=`dirname "$0"`
+cosmos_dir=`realpath $this_dir/../../../../gnd/cosmos`
+assembly_dir=`realpath $this_dir/..`
+$cosmos_dir/build_cosmos_plugin.sh $assembly_dir >/dev/null