.. _usage_gen_msgs:

Generated ROS Message Plugin
############################

Source code generated by :docsite:`cx_ros_comm_gen`.

Given the *package* (e.g., ``std_msgs``) and *msg_name* (e.g., ``String``), this document uses the following abbreviations:

 - **PkgCamel**: CamelCase of *package* (e.g., ``StdMsgs``)
 - **MsgCamel**: CamelCase of *msg_name* (e.g., ``String``)
 - **pkg-kebab**: kebab-case of *package* (e.g., ``std-msgs``)
 - **msg-kebab**: kebab-case of *msg_name* (e.g., ``string``)

.. admonition:: Plugin Class

  cx::CX\ **PkgCamelMsgCamel**\ Plugin

  (e.g., cx::CXStdMsgsStringPlugin)

Configuration
*************
This plugin has no specific configuration.

Features
********
Facts
~~~~~

.. code-block:: lisp

  ; Asserted by the respective create-subscription function.
  ; Retracted by the respective destroy-subscription function.
  (<pkg-kebab>-<msg-kebab>-subscription (topic ?topic-name-string))

  ; Asserted by the respective create-publisher function.
  ; Retracted by the respective destroy-publisher function.
  (<pkg-kebab>-<msg-kebab>-publisher (topic ?topic-name-string))

  ; Asserted by the callback of a subscriber whenever a message arrives.
  ; Process the message and then call destroy-message before retracting!
  (<pkg-kebab>-<msg-kebab>-message (topic ?topic-name-string) (msg-ptr ?msg-ptr))

Functions
~~~~~~~~~

.. code-block:: lisp

  ; Create and destroy publishers and subscriptions.
  (<pkg-kebab>-<msg-kebab>-create-publisher ?topic-name)
  (<pkg-kebab>-<msg-kebab>-destroy-publisher ?topic-name)
  (<pkg-kebab>-<msg-kebab>-create-subscription ?topic-name)
  (<pkg-kebab>-<msg-kebab>-destroy-subscription ?topic-name)

  ; Publish a given message over a topic.
  ; Requires the publisher to be created first using create-publisher.
  (<pkg-kebab>-<msg-kebab>-publish ?msg-ptr ?topic-name)

  ; Create a message and return a pointer to it
  (bind ?msg-ptr (<pkg-kebab>-<msg-kebab>-create-message))
  ; Destroy a message, call this after publishing a message or processing an incoming message to prevent it from staying in memory.
  (<pkg-kebab>-<msg-kebab>-destroy-message ?msg-ptr)

  ; Populate the field of a message.
  ; If the field is a message, then pass a pointer to that message (by using that respective messages bindings).
  (<pkg-kebab>-<msg-kebab>-set-field ?msg-ptr ?field-name ?field-value)

  ; Retrieve a field of a message.
  ; If the field is a message, then a pointer is returned that can only be processed by using that respective messages bindings.
  (<pkg-kebab>-<msg-kebab>-get-field ?msg-ptr ?field-name)

Usage Example
*************

A minimal working example is provided by the :docsite:`cx_bringup` package. Run it via:

.. code-block:: bash

    ros2 launch cx_bringup cx_launch.py manager_config:=plugin_examples/string_msg.yaml

It creates a ``std_msgs/msg/String`` subscription on topic ``/ros_cx_in`` and prints out any text send over it.
Additionally, it creates a publisher on ``/ros_cx_out`` that publishes ``Hello World`` whenever something is received over the ``/ros_cx_in`` topic.

Configuration
~~~~~~~~~~~~~

File :source-master:`cx_bringup/params/plugin_examples/string_msg.yaml`.

.. code-block:: yaml

   clips_manager:
     ros__parameters:
       environments: ["cx_string_msg"]
       cx_string_msg:
         plugins: ["executive", "string_msg", "files"]
         log_clips_to_file: true
         watch: ["facts", "rules"]

       executive:
         plugin: "cx::ExecutivePlugin"
         publish_on_refresh: false
         assert_time: true
         refresh_rate: 10
       string_msg:
         plugin: "cx::CXStdMsgsStringPlugin"
       files:
         plugin: "cx::FileLoadPlugin"
         pkg_share_dirs: ["cx_bringup"]
         load: [
           "clips/plugin_examples/string-msg.clp"]


Code
~~~~

File :source-master:`cx_bringup/clips/plugin_examples/string-msg.clp`.

.. code-block:: lisp

  (defrule string-pub-sub-init
  " Create a simple publisher and subscriber using the generated bindings. "
    (not (std-msgs-string-subscription (topic "ros_cx_in")))
    (not (std-msgs-string-publisher (topic "ros_cx_out")))
  =>
    (std-msgs-string-create-publisher "ros_cx_out")
    (printout info "Created publisher for /ros_cx_out" crlf)
    (std-msgs-string-create-subscription "ros_cx_in")
    (printout info "Listening for String messages on /ros_cx_in" crlf)
  )

  (defrule string-publisher-recv-and-answer
  " React to incoming messages and answer (on a different topic) "
    (std-msgs-string-subscription (topic ?sub))
    ?msg-f <- (std-msgs-string-message (topic ?sub) (msg-ptr ?inc-msg))
    (std-msgs-string-publisher (topic ?pub))
    =>
    ; fetch the content of the message and print it
    (bind ?recv (std-msgs-string-get-field ?inc-msg "data"))
    (printout blue "Recieved via " ?sub " :" ?recv crlf)
    ; make sure to actually destroy the message to free heap-allocated memory for it, once the message is processed and can be removed
    (std-msgs-string-destroy-message ?inc-msg)
    (retract ?msg-f)

    ; example of how to create and send a new message
    (printout green "Sending Hello World Message in response!" crlf)
    (bind ?msg (std-msgs-string-create-message))
    (std-msgs-string-set-field ?msg "data" "Hello world!")
    (std-msgs-string-publish ?msg ?pub)
    ; destroy the msg after usage to free up the memory
    (std-msgs-string-destroy-message ?msg)
  )

  (defrule string-msg-pub-sub-finalize
  " Delete the subscription and publisher on executive finalize. "
    (executive-finalize)
    (std-msgs-string-subscription (topic ?sub))
    (std-msgs-string-publisher (topic ?pub))
  =>
    (printout debug "Destroying subscription " ?sub crlf)
    (printout debug "Destroying publisher " ?pub crlf)
    (std-msgs-string-destroy-subscription ?sub)
    (std-msgs-string-destroy-publisher ?pub)
  )

  (defrule ros-msgs-message-cleanup
  " Delete any incoming msg on executive finalize. "
    (executive-finalize)
    ?msg-f <- (std-msgs-string-message (msg-ptr ?ptr))
  =>
    (std-msgs-string-destroy-message ?ptr)
    (retract ?msg-f)
  )