Skip to content

Commit

Permalink
Update alarms.rst
Browse files Browse the repository at this point in the history
  • Loading branch information
@MrinallU
MrinallU authored Aug 28, 2023
1 parent bab1ef3 commit 22ad87a
Showing 1 changed file with 134 additions and 35 deletions.
169 changes: 134 additions & 35 deletions docs/reference/alarms.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,85 +2,184 @@
-----------------------------------------
**Overview**

In the realm of building dependable control systems, the imperative for error detection and effective error-handling mechanisms cannot be overstated. Within this context, MIL (Mission Impossible Labs) presents a robust solution in the form of a dynamic live alarm system. This alarm system operates discreetly in the background of both the robot's mission and driver codebases, ready to be activated upon the emergence of errors. Notably, the alarm code doesn't solely serve to identify and address errors; it can also adeptly manage changes that extend beyond error scenarios.
In the realm of building dependable control systems, the importance of error detection and effective error-handling mechanisms cannot be overstated. Within this context, MIL presents a robust solution in the form of a live alarm system. This alarm system operates discreetly in the background of both the robot's mission and driver codebases, ready to be activated upon the emergence of errors. Notably, the alarm code doesn't solely serve to identify and address errors; it can also adeptly manage changes or updates that extend beyond error scenarios.

**ROS Alarms: A Service-Oriented Architecture**

The architecture of ROS alarms distinguishes itself by employing a service-oriented model rather than the customary topic-based approach. In ROS, Services act as the conduits for interaction between nodes, functioning in a request-response manner. While ROS topics enable asynchronous data exchange, services facilitate nodes in seeking specific actions or information from other nodes, awaiting a subsequent response before proceeding. This proves especially valuable in tasks necessitating direct engagement, such as data retrieval or computations.
The architecture of ROS alarms distinguishes itself by employing a service-oriented model rather than the usual topic-based approach. In ROS, Services act as the conduits for interaction between nodes, functioning in a request-response manner. While ROS topics enable asynchronous data exchange, services facilitate nodes in seeking specific actions or information from other nodes, awaiting a subsequent response before proceeding. This method of waiting before proceeding is known as a synchronous data exchange. This proves especially valuable in tasks that require direct engagement, such as data retrieval or computations.

**Components of a ROS Service**

A ROS service structure is bifurcated into two pivotal components:
A ROS service structure is bifurcated into two components:

1. **Server**: This node takes on the role of service provision, awaiting incoming requests from other nodes. Essentially, it executes the operation stipulated by the service.
1. **Server**: This node provides the service and waits for incoming requests from other nodes. In simpler terms it carries out the operation you have specified. .

2. **Client**: In contrast, this node is responsible for transmitting requests to the service server, then patiently awaiting the corresponding response.
2. **Client**: This node sends requests to the service server and waits for the response.

For a concrete illustration, consider the case of a service designed to sum two integers:
For a concrete illustration, consider the case of a service designed to query and update an array of integers:

1. **Define the Service Messages**

Create two separate service message files in your ROS package's `srv` folder:

- `ArrayUpdate.srv`:
```plaintext
# ArrayUpdate.srv
int32 index
int32 value
---
bool success
```

- `ArrayQuery.srv`:
```plaintext
# ArrayQuery.srv
int32 index
---
int32 value
```

2. **Implement the Service Server**

Create a Python script named `array_service_server.py`:

Server Implementation:
```python
#!/usr/bin/env python
import rospy
from service_example.srv import AddTwoInts, AddTwoIntsResponse
def handle_add_two_ints(req):
sum_result = req.a + req.b
rospy.loginfo(f"Adding {req.a} + {req.b} = {sum_result}")
return AddTwoIntsResponse(sum_result)
def add_two_ints_server():
rospy.init_node('add_two_ints_server')
service = rospy.Service('add_two_ints', AddTwoInts, handle_add_two_ints)
rospy.loginfo("Ready to add two ints.")
from your_package_name.srv import ArrayUpdate, ArrayQuery
from std_msgs.msg import Int32MultiArray
class ArrayServiceServer:
def __init__(self):
self.array_data = [10, 20, 30, 40, 50]
def handle_array_update(self, request):
if 0 <= request.index < len(self.array_data):
self.array_data[request.index] = request.value
return ArrayUpdateResponse(True)
else:
return ArrayUpdateResponse(False)
def handle_array_query(self, request):
if 0 <= request.index < len(self.array_data):
return ArrayQueryResponse(self.array_data[request.index])
else:
return ArrayQueryResponse(-1) # Invalid index
def main():
rospy.init_node('array_service_server')
server = ArrayServiceServer()
rospy.Service('array_update', ArrayUpdate, server.handle_array_update)
rospy.Service('array_query', ArrayQuery, server.handle_array_query)
rospy.spin()
if __name__ == '__main__':
add_two_ints_server()
main()
```

Replace `your_package_name` with the actual name of your ROS package.

3. **Implement the Service Clients**

Create two separate Python scripts for interacting with the service:

- `array_update_client.py`:
```python
#!/usr/bin/env python
import rospy
from your_package_name.srv import ArrayUpdate
def array_update_client(index, value):
rospy.wait_for_service('array_update')
try:
array_update = rospy.ServiceProxy('array_update', ArrayUpdate)
response = array_update(index, value)
return response.success
except rospy.ServiceException as e:
print("Service call failed:", e)
if __name__ == '__main__':
rospy.init_node('array_update_client')
index_to_update = 2
new_value = 35
success = array_update_client(index_to_update, new_value)
if success:
print(f"Value at index {index_to_update} was updated to {new_value}")
else:
print(f"Failed to update value at index {index_to_update}")
```

Client Implementation:
- `array_query_client.py`:
```python
#!/usr/bin/env python
import rospy
from service_example.srv import AddTwoInts, AddTwoIntsRequest
from your_package_name.srv import ArrayQuery
def add_two_ints_client(a, b):
rospy.wait_for_service('add_two_ints')
def array_query_client(index):
rospy.wait_for_service('array_query')
try:
add_two_ints = rospy.ServiceProxy('add_two_ints', AddTwoInts)
response = add_two_ints(a, b)
return response.sum
array_query = rospy.ServiceProxy('array_query', ArrayQuery)
response = array_query(index)
return response.value
except rospy.ServiceException as e:
rospy.logerr("Service call failed: %s", e)
print("Service call failed:", e)
if __name__ == '__main__':
rospy.init_node('add_two_ints_client')
a = 10
b = 5
result = add_two_ints_client(a, b)
rospy.loginfo(f"Sum of {a} and {b} is {result}")
rospy.init_node('array_query_client')
index_to_query = 2
value = array_query_client(index_to_query)
if value != -1:
print(f"Value at index {index_to_query}: {value}")
else:
print(f"Invalid index {index_to_query}")
```

Replace `your_package_name` with your actual ROS package name.

4. **Launch the Service Server**

Adjust the ROS package name and make sure you've built your package.

- Start the service server:
```bash
rosrun your_package_name array_service_server.py
```

- Run the service update client:
```bash
rosrun your_package_name array_update_client.py
```

- Run the service query client:
```bash
rosrun your_package_name array_query_client.py
```

**Alarm System Logic**

The alarm system's functionality is more intricate than the preceding example. In this scenario, the server is engineered to manage not numeric calculations, but the tasks of updating, setting, and querying alarm data. Unlike the single-client model, ROS alarms encompass two distinct types of clients: the alarm broadcaster and the alarm listener. The broadcaster initializes and triggers alarms in response to errors or changes, while the listener monitors the broadcaster's activity and activates designated callback functions when alarms are raised.
The alarm system's functionality is more intricate than the preceding example. In this scenario, the server is engineered to manage not numeric calculations, but the tasks of updating, setting, and querying alarm data. Unlike the single-client model, ROS alarms encompass two distinct types of clients: the alarm broadcaster and the alarm listener. The broadcaster initializes and triggers alarms in response to errors or changes, while the listener monitors the broadcaster's activity and activates designated a callback function when alarms are raised. The callback function should handle the error or change appropriately.

To peruse the detailed alarm system code, refer to the repository: [https://github.com/uf-mil/mil/tree/master/mil_common/ros_alarms](https://github.com/uf-mil/mil/tree/master/mil_common/ros_alarms)

To successfully leverage alarms, the initiation of both the broadcaster and listener is requisite. The listener should be configured to execute a predefined callback function, addressing errors or changes detected by the broadcaster. Within your codebase, error detection and alarm raising procedures should be integrated. If orchestrated adeptly, the callback function will be automatically invoked, underscoring successful error mitigation.
To successfully leverage alarms, the initialization of both the broadcaster and listener is needed. The listener should be configured to execute a predefined callback function, addressing errors or changes detected by the broadcaster. Within your codebase, error detection and alarm-raising procedures should be integrated. If orchestrated correctly, the callback function will be automatically invoked, underscoring successful error mitigation.

For a practical example of this workflow, visit: [https://github.com/uf-mil/mil/blob/master/mil_common/ros_alarms/test/rospy/callback_test.py](https://github.com/uf-mil/mil/blob/master/mil_common/ros_alarms/test/rospy/callback_test.py)

**Applications and Context**

The applications of ROS alarms span various contexts, with one notable application residing in the control of the submersible vehicle's thrust and kill board. The thrust and kill board, responsible for the sub's electronic operations, is integrally associated with ROS alarms. Upon the board's activation or deactivation (hard or soft kill), alarms are invoked to apprise users of these changes. The listener's callback function comes into play, ensuring that alarms are updated in alignment with the board's current state. This intricate process, triggered each time the board is deactivated, creates a system whereby users are continually informed about the board's status changes – essentially manifesting a dynamic live alarm system.
The applications of ROS alarms span various contexts, with one notable application residing in the control of the submersible vehicle's thrust and killboard. The thrust and killboard, responsible for the sub's electronic operations, is integrally associated with ROS alarms. Upon the board's activation or deactivation (hard or soft kill), alarms are invoked to apprise users of these changes. The listener's callback function comes into play, ensuring that alarms are updated in alignment with the board's current state. This process, triggered each time the board is deactivated, creates a system whereby users are continually informed about the board's status changes – essentially manifesting a dynamic live alarm system.

To delve into the implementation, visit: [https://github.com/uf-mil/mil/blob/master/SubjuGator/drivers/sub8_thrust_and_kill_board/sub8_thrust_and_kill_board/handle.py](https://github.com/uf-mil/mil/blob/master/SubjuGator/drivers/sub8_thrust_and_kill_board/sub8_thrust_and_kill_board/handle.py)

.. automodule:: ros_alarms

Python
Expand Down

0 comments on commit 22ad87a

Please sign in to comment.