Skip to content

Latest commit

 

History

History
402 lines (268 loc) · 822 KB

UserGuide.md

File metadata and controls

402 lines (268 loc) · 822 KB

User Guide

MRI Monitoring Device

As part of the GBM8970 course
For the UNF
By Project Team #2: MRI Monitoring System

Introduction

This guide explains how to install and operate the MRI monitoring system designed for the UNF as part of the GBM8970 course. It aims to achieve two main objectives:

  1. Understand how to install the solution.
  2. Explain how the solution is built in order to facilitate repair and maintenance.

Table of Contents

Introduction 1

Table of Contents 1

How to Install Prometheus 2

How to Install Grafana 4

How to Create a Grafana Dashboard 5

Alerts in Dashboards 5

Alert List 5

Alert Graph 5

Alert State History 6

How to Create Alerts in Grafana 7

Alert rules 7

Contact points 8

Notification Templates 9

Notification Policies 9

How to Connect Components to the PCB 10

How to Connect Components to the CB Connectors 12

List of Components 13

Arduino Code Modifications 14

Potential Errors 14

Maintenance 14

SAFETY WARNINGS
The box and its components are magnetic and must not be moved into the MRI room in order to avoid the risk of injury.

How to Install Prometheus

The following procedure explains how to install Prometheus, which acts as a temporary data store until the data is retrieved by Grafana. This method is intended for use on a standalone computer. On the UNF server, this application is launched via Docker Compose.

  1. First, Prometheus must be downloaded onto the host server. To do so, follow this link: https://prometheus.io/download/
    1. Select the operating system of the server.
Figure 1: Système d’exploitation
  1. Choose the LTS (Long Term Support) version for better stability and download the .zip file. Transfer this file to the desired folder on the server.
Figure 2: LTS Version
  1. You will also need the Prometheus Pushgateway to temporarily host data coming from the Arduino until it is imported by Prometheus. By scrolling through the Prometheus download page, you will find the section related to the Pushgateway.
Figure 3: Pushgateway

  1. The installation of Prometheus and Pushgateway comes by default with a .yml file that serves as the configuration file for the applications. These files will be empty upon download. To ensure the expected behavior of the system, replace the default .yml file in the folder with the one provided with the solution (included in the Docker Compose file).

  2. By default, the applications use ports 9090 and 9091 respectively. These can be changed by modifying the corresponding lines in the Docker Compose file. Once this step is complete, both applications should be functional.
Figure 4: Docker Compose File

How to Install Grafana {#how-to-install-grafana}

Grafana is the application used to generate graphs, visualize data, create alerts, and manage them. To get started, you can follow the link below to download the appropriate version of Grafana based on your operating system. For the version, select the latest available release. This procedure is also for installation when using a standalone computer. On the UNF servers, this application is launched via Docker Compose.
https://grafana.com/grafana/download
Figure 5: Download Grafana

The download can be done in two different ways, regardless of the chosen operating system: either via standalone binary or by installing directly. For each option, an installation guide can be found just below the selected version.
Figure 6: User Guide to Download Grafana

By simply following these guides, you can proceed with the Grafana installation.
Additional information: The enterprise version is preferred, as it provides access to enterprise features without the need to redo the process if needed.
By default, the port used is 3000. This port is often either already in use or requires special permissions. To change this port, you can follow the procedure below, where the folder paths are highlighted in gray:

  1. Open the conf directory and copy sample.ini to custom.ini.
  2. Modify custom.ini and comment out the http_port configuration line using the semicolon symbol (;).
  3. Change the port to your desired one, such as 8080.

How to Create a Grafana Dashboard {#how-to-create-a-grafana-dashboard}

The following procedure explains how to create a Grafana dashboard:

  1. Select Dashboards from the main menu, then click New Dashboard.
  2. You can add a visualization to display data by clicking Add visualization, share a visualization with other dashboards via Add a library panel, or import dashboards using Import a dashboard.
  3. Select a data source (e.g., Prometheus).
  4. You can modify the dashboard by adding various panels (e.g., Time series, State timeline, Bar chart, Gauge, Logs, Alert list, etc.), arrange the panels in different sections (Row), and import from a library.

Alerts in Dashboards {#alerts-in-dashboards}

Alert List {#alert-list}

After linking the alerts to a specific panel of the dashboard (refer to the alert rules instructions), you can display the alerts in your dashboard by selecting the Alert list panel. The displayed alerts can then be filtered; for example, you can choose to display only alerts in "firing" mode or in "normal" mode.
Figure 7: Alert List on the Grafana Dashboard

Alert Graph {#alert-graph}

When displaying the graph of data related to an alert (for example, water temperature data), the graph can show the status of the alert(s).

  1. Create the graph panel, such as Time series.
  2. Link the alerts to the panel.
  3. If the alerts are based on modified data, such as being averaged over an hour, it is useful to display the data with the same modification applied to the alert.
  4. A green heart (normal) or a broken red heart (firing) will be placed to the right of the panel title, indicating the alert status. If at least one alert is in "firing" mode, the heart will be red.
  5. You can display a dashed green line (normal) or a broken red line (firing) on the graph to indicate the time at which an alert was triggered.
    1. In the Settings of the dashboard, go to the Annotations section.
    2. In the Query "Annotations & Alerts (Built-in)", ensure that the query is set to Enabled and is filtered by Dashboard.
Figure 8: Graph Showing Alert Logs

Alert State History {#alert-state-history}

It is possible to access the alert history.

  1. After linking your alert to the dashboard panel, open the Edit mode of your panel.
  2. Go to the Alert section where the alerts linked to the dashboard panel are displayed.
  3. Click the arrow next to the specific alert.
  4. Click Show state history, and you will see the triggered and resolved alerts (Alerting, Normal, Normal (Paused), or Normal (Updated)), along with the name of the triggered metric, its value, and its trigger date and time. It will also display the metric and its value.
Figure 9: Logs of Alerts Status

How to Create Alerts in Grafana {#how-to-create-alerts-in-grafana}

To create an alert in Grafana, there are three steps to follow in the Alerting section:

  1. Alert rules: Set the condition for the alert.
  2. Contact points: Determine where the alert is sent.
  3. Notification policies: Define which alert is sent to which contact point.
Figure 10: How to Create an Alert in Grafana

Alert rules {#alert-rules}

The following procedure explains how to create an alert:

  1. Select New alert rule.
  2. Choose the alert name in Section 1 - Enter alert rule name.
  3. Define the alert condition in Section 2 - Define query and alert condition.
    1. Section A : Choose the Prometheus data and the metric to retrieve and monitor using a query. Operations can be applied to the data: Aggregations, Range functions, Functions, Binary operations, Trigonometric, Time functions. For example, to calculate the rounded average value over the last hour, select Range functions → avg over time with an interval of 1 hour, and Functions → round.
    2. **Section B - Reduce (**This step may not be necessary and can be removed)
      1. Input: Choose the data to modify, defaulting to A (from Section A).
      2. Function: Choose the method to transform the data: Min, Max, Mean, Median, Sum, Count, Last.
      3. Mode: Strict, Drop Non-numeric Values, Replace Non-numeric Values.
    3. Section C - Threshold : Choose the threshold at which the alert will be triggered.
      1. Input: Choose the data monitored by Grafana (A, B, or C, depending on the section).
      2. Choose the condition to trigger the alert: Is above, Is below, Is within range, Is outside range. Be mindful of the units.
    4. Additional operations can be applied to modify the data using Add expressions (Math, Reduce, Resample, Classic condition, Threshold).
    5. Test the alert using Preview.
  4. Section 3 - Set evaluation behavior : Allows you to manage multiple alert rules within folders and groups.
    1. Folder: Choose an existing folder or create a new one to store the alert rule.
    2. Evaluation group and interval: Used when multiple alert rules are evaluated over the same time interval. You can change the interval at which the alert is checked.
    3. Pending period: The time period before the alert is triggered.
  5. Section 4 - Configure labels and notifications
    1. Labels: They can be used to search, route alerts to different contact points, and provide context in the alert details.
    2. Notifications: Select who should receive a notification when the alert triggers, using the Contact point.
  6. Section 5 - Configure notification message
    1. This section allows you to include information in the alert notification (Summary, Description, Runbook URL). You can also link the alert to a dashboard to display it with Link dashboard and panel.
  7. You can export the alert in JSON, YAML, or Terraform (HCL).
  8. You can pause an alert by selecting Pause evaluation.

Contact points {#contact-points}

Defining contact points allows you to specify where the alert will be sent. These contact points are then assigned in the Alert Rules (step 5.2) or Notification Policies.

  1. Select Create contact point.
  2. Define the contact name.
  3. Choose the channel used to send the alert. A contact point can have multiple destinations. Several destination options are available:
    1. Alertmanager, Amazon SNS, Cisco Webex Teams, DingDing, Discord, Email, Google Chat, Grafana Oncall, Kafka REST Proxy, Line, Microsoft Teams, MQTT, Opsgenie, Pagerduty, Pushover, Sensu Go, Slack, Telegram, Threema Gateway, VictorOps, Webhook, WeCom.
  4. Fill in the necessary information based on the selected channel. For example, an email address for email, or the channel and users for Slack.
  5. In Optional settings, additional information can be added. For example, for Slack, you can define an alert title or message body template using the templates in Notification Templates.
  6. There is an option to disable the Resolved message when the alert is resolved.
  7. The contact point is tested by sending a Notification message.
  8. Save the contact point.

Notification Templates {#notification-templates}

It is possible to create templates for contact points to customize the notification models sent. Grafana provides a default template for the title and message of the notification. Here's an example for the message of an alert:
Figure 11: Example of Alert Message

Notification Policies {#notification-policies}

Defining notification policies allows you to determine how alerts are routed to contact points.

  1. Select New child policy.
  2. Define the condition that triggers the alert to be sent by selecting a label and the associated value (e.g., =, !=, =~, !~). It is important that the label in question has been defined in the alert rule.
Grafana Labs, Notification policies, consulté le 12 février 2025, https://grafana.com/docs/grafana/latest/alerting/fundamentals/notifications/notification-policies/
Figure 12: Notification Policies
  1. Choose the contact point.
  2. You can enable several options:
    1. Continue matching subsequent sibling nodes
    2. Override grouping
    3. Override general timings
    4. Mute timings
  3. Save the policy.

How to Connect Components to the PCB {#how-to-connect-components-to-the-pcb}

This section explains how the sensors (fluid thermometers, temperature/humidity sensors, and flow meter), the power supply, the Arduino Opta, and the Arduino extension are connected to the PCB in case they become disconnected and need to be reconnected. The PCB schematic is shown in Figure 13, the PCB itself is presented in Figure 14, and the connections are illustrated in Figure 15.
Figure 13: PCB Diagram on KiCad
Figure 14: PCB Design on KiCad
Figure 15: PCB Wiring Diagram

Below is a list describing the connection of each component (note that the left or right direction of the connections refers to the direction in Figure 15):

  • The power supply is connected to the PCB with a two-pin JST connector called BT1. The left pin (red) corresponds to +12V and the right pin (black) corresponds to ground.
  • The Arduino Opta is connected to the PCB with a four-pin JST connector called J1. From left to right, the first pin (black) corresponds to pin I4 of the Arduino, the second pin (black) corresponds to pin I3 of the Arduino, the third pin (black) corresponds to the ground of the Arduino (pin “-”), and the fourth pin (red) corresponds to the +12V power supply of the Arduino (pin “+”).
  • The Arduino extension is connected to the PCB with a two-pin JST connector called J2. The left pin (red) corresponds to the ground of the extension (pin “-”), and the right pin (black) corresponds to the +12V power supply of the extension (pin “+”).
  • The fluid thermometers are each connected to the PCB with a two-pin JST connector called TH1 or TH2, depending on the thermometer. Since these thermometers are technically resistors, the orientation of their connection does not affect their operation. Thermometer TH1 is connected to pins 1 and 2 of the 6-pin CB connector, and thermometer TH2 is connected to pins 5 and 6 of the 6-pin CB connector.
  • The temperature and humidity sensor is connected to the PCB with a four-pin JST connector called J3. From left to right, the first pin (red) corresponds to the +12V power supply and is connected to pin 2 of the 4-pin CB connector, the second pin (black) corresponds to ground and is connected to pin 1 of the 4-pin CB connector, the third pin (black) corresponds to the A pin of the Modbus of the Arduino Opta and is connected to pin 4 of the 4-pin CB connector, and the fourth pin (black) corresponds to the B pin of the Modbus of the Arduino Opta and is connected to pin 3 of the 4-pin CB connector. It is important to note that the A and B Modbus connections exit the PCB to the Arduino Opta via a two-pin JST connector called J4. The left pin (black) corresponds to the A pin, and the right pin (red) corresponds to the B pin.
  • The flow meter is connected to the PCB with a three-pin JST connector called J5. From left to right, the first pin (yellow) corresponds to the +12V power supply and is connected to pin 3 of the 6-pin CB connector, the second pin (black) corresponds to ground and is connected to pin I1- of the Arduino extension, and the third pin (red) corresponds to data transmission and is connected to pin 4 of the 6-pin CB connector. It is important to note that the data transmission branch exits the PCB to the Arduino extension via a two-pin JST connector called J6. The left pin (black) is unused, and the right pin (red) corresponds to data transmission. This is connected to pin I1+ of the Arduino extension.

How to Connect Components to the CB Connectors {#how-to-connect-components-to-the-cb-connectors}

The CB connectors with 4 and 6 pins for data transmission from the MRI room and the chiller are organized as follows:
Figure 16: PCB Connector Diagram

In the event that one of the connectors no longer works or a wire breaks/solders off, it can be re-soldered by following this diagram. The Seeedstudio S-TH-01 temperature sensor has the following connections:

  • Red wire: Power supply, +12V
  • Black wire: Ground
  • Yellow wire: Modbus A
  • White wire: Modbus B

The water thermometers TH1 and TH2 can be connected either way without consequences since they are thermistors.

The 4-20mA module of the Flomec Q9 flow meter has the following connections:

  • Red wire: Power supply, +12V
  • Black wire: Flow, 4-20mA
  • White wire: Pulse out (+)
  • Green wire: Pulse out (-)

The green and white wires are not used, as a pulse device is not installed in the solution. They are only used to transmit the number of liters that have passed through the flow meter. The two wires work in such a way that depending on the calibration done on the flow meter, a certain number of pulses are sent to indicate the number of liters. So, if it is calibrated that each pulse equals one liter, the equipment will send a pulse each time one liter passes through the pipe. The two wires provide the same information, but the difference is that the white wire goes from 1 to 0 to make its pulse, while the green wire goes from 0 to 1.

List of Components {#list-of-components}

The complete monitoring device includes the following parts:

  • 1 Arduino Opta
  • 1 Arduino extension AFX00007
  • 2 GE-2093 fluid thermometers from Amphenol Advanced Sensors
  • 1 S-TH-01 temperature and humidity sensor from Seeed Studio
  • 1 Q9 Display flow meter from Flomec
  • 1 4-20 mA shield for the Flomec Q9 Display
  • 1 operational amplifier LM324N
  • 2 resistors of 3 kΩ
  • 1 resistor of 10 kΩ
  • 1 resistor of 14 kΩ
  • 6 JST S2B-EH connectors
  • 1 JST S3B-EH connector
  • 2 JST S4B-EH connectors
  • 1 CB 4-pin connector
  • 1 CB 6-pin connector
  • 1 screw terminal for power supply
  • 1 AC/DC 12V transformer
  • 1 CHKO1086 enclosure
  • 1 steel DIN rail
  • 4 rubber feet
  • 4 nuts/washers and 1/4" bolts for foot installation
  • 4 M3 nuts for PCB mounting

Arduino Code Modifications {#arduino-code-modifications}

It is possible that, during the use of the solution, you may want to make changes to its operation. If this modification involves changing the Arduino code, follow the procedure below:

  1. Make sure the Arduino IDE is installed on the computer of your choice. This is the interface used to program the Arduino Opta contained in the box.
  2. Remove the filler ring located to the left of the opening for the Ethernet cable. To do this, open the box and gently push the ring outward. It should come off easily.
  3. Connect the Arduino to the computer using a USB-C to USB cable through this new opening.

Note: The first time you connect the Arduino, you might not see the code currently running on the device. We recommend creating a new file in the Arduino IDE and pasting in the code provided in the project’s GitHub repository. You will most likely need to install the required libraries. These are natively available in Arduino and will be suggested via a pop-up window.

  1. Make the desired changes to the code, then upload this version to the device. Once the upload is complete, the Arduino will automatically restart the code.

Note: This step may take some time to compile.

  1. Disconnect the cable linking the Arduino to the computer and reseal the opening with the filler ring.

These steps will be necessary to adjust the behavior of the flow meter. The relevant section of the code is located between lines 75 and 79. The rest of the code is well-commented and allows for easy understanding of each line so you can make accurate adjustments.

Potential Errors {#potential-errors}

Here is a list of errors that may occur during use, along with potential causes:

  • No data displayed on Grafana
    • Possible Ethernet connection issue
    • Possible power loss
  • A sensor is sending abnormal (erroneous) or zero data
    • Incorrect sensor wiring
    • Sensor failure
    • Issue with the Arduino Opta
    • If the flow meter sends incorrect data, the issue may lie with the Arduino extension module

Maintenance {#maintenance}

Regularly check that no dust or debris is obstructing the temperature and humidity sensor or accumulating inside the main enclosure. If necessary, clean the device using a cloth, duster, or any appropriate tool. Do not apply water or soap to the solution.

In case of a component failure, refer to this document to perform proper repairs.