D4. User Manual

Overview

This documentation manual is designed to support all users of the Wavemaker research team. It is a full-on manual dedicated to guide and understand the functioning of the entire hardware as well as the graphical user interface (GUI). All the content available in the manual is listed on the table of contents and hyperlinked to the corresponding sections. This manual should also be used by any future teams that wish to implement updates and new features to the GUI.

GUI Purpose

This GUI is designed to control the motors/pistons that create waves in the most user-friendly and understandable way possible. A user will be able to select the motors they want to turn on, define the parameter values and run mode for these motors (presets, curve IDs, or plain manual parameters), and finally start the motors to create a wave. The GUI should allow for the simple, understandable and effective use of the equipment.

Expected Use

To start, in order for the GUI to work, all hardware devices must be on and running. Users will have full control over the device and the parameter values assigned to the motors in order to control motion. Users also will have access to preset CSV files which can be uploaded to create motion for expected outcomes – most effective for demonstration purposes. This manual’s explanation of the parameters and their intended use/effect will also support experimentation for users of the machine.

System Start-Up

Hardware:

  • Flip up the big silver switch on the wall behind the computer
  • In the big black hardware housing to the right of the computer, turn the small horizontal black switch to on
  • After waiting a few seconds for the voltage to build, press the green button and the voltage reading should shoot up

Software:

  • On the desktop, click on the icon that says Open Wavemaker GUI
  • A terminal window should pop up, and Studio 5000, should begin to load – MAKE SURE TO NOT PRESS ENTER UNTIL TURNING THE MOTORS ON IN STUDIO5000
  • Once Studio 5000 loads, click the ‘Offline’ drop down and select ‘Go Online’
  • The drop down should turn green and display ‘Rem Run’
  • (OPTIONAL) Open up the helpful visualization tool in Studio 5000 by going to Tasks > Main Task > Wave_Control and double clicking on A_1_Control
  • Minimize Studio 5000 and click back on the terminal screen; hit the enter key and the GUI will load onto the screen

Tab Breakdown

  • Control Home: This tab is for the general controls of the motors. At the top, is a visualization of all 30 motors as small white circles. As the motors are turned on and in use, these motors will turn green. Next, preparing the motors sets them in the correct starting position before motion. From here, we can start the motors for one stroke or continuous motion, and then stop the motors. Also, start curve can be done from this tab.
  • Define Motors: This tab is used to select the motors that we want to use. After clicking the check boxes for our desired motors, clicking the ‘Activate Selected Motors’ button will turn the motors on and prepare them for motion. We will then define the motor’s parameters in one of three ways: by group, by column, by row, or all at once. After defining their values, the ‘Write Motor Attributes’ button will assign the values to the motors. Once these three steps have been completed, the motion can be started from the Control Home tab.
  • Preset Options: After selecting the motors that are desired for motion, rather than defining the parameters in one of the four ways listed above, this tab allows for the selection of preset values. The ‘Select Preset’ button allows the user to browse the machine to select the CSV file they wish to upload with predetermined parameter values. After selecting the file, the values will populate a collapsible frame object on the tab. Then the ‘Apply Preset’ button will write the values to the motors. Now the preset can be run from the Control Home tab.
  • Feedback: Throughout interacting with the GUI, this tab will contain any feedback from various actions done with the hardware. There will be success, info, debugging, error, and critical messages added here throughout the course of starting up the motors. If the user is encountering errors/issues with the GUI and/or hardware, this will be the first place to look for understanding what the error could be and how to rectify the situation.

Creating a Wave

Define Motors and Activate

  • Go to the ‘Define Motors’ tab
  • Select the motors that you want to use
  • Click the ‘Activate Selected Motors’ Button
  • Select the manner in which you want to define your motors: by row, by column, group, or all together
  • Adjust the parameter values to the values of your choice

Prepare Motors

  • Go to the ‘Control Motors’ tab
  • The activated pistons should be highlighted green on the visualization at the top
  • Press the ‘Home Motors’ button
  • The selected pistons should start homing – they should move down and back up all aligning to the specific starting position.

Start Motors

  • Select desired type of motion: ‘One Stroke’ or ‘Continuous’
  • Press the ‘Start Motors’ button
  • The pistons should begin moving up and down based on the parameters which you set
  • After being ran, pistons can be stopped at any time with the ‘Stop Motors’ button (and it is preferred to stop them at the bottom of their motion to make the future starting process faster)

Process for Presets

  • On the ‘Define Motors’ tab, select the motors you would like to use
  • Click the ‘Activate Selected Motors’ button
  • On the ‘Presets’ tab, click the ‘Select Preset’ button
  • A dialog box should pop up that allows you to select a CSV file from the machine – select the file you would like and press ‘Open’
  • On the ‘Control Home’ tab, you can home and start the motors as described above

Process for Start Curve

  • WIP

Create New Presets

Presets are run by loading a CSV file that is saved in the ‘Presets’ folder in this project. These presets are very powerful, and a user is able to create their own very easily:

  • From the desktop, navigate to GUI_prototype > Presets > Preset Outline
  • Right click and copy that file
  • Right click again (within the same Presets Folder) and paste the file
  • Rename the file (if desired) trying to make it descriptive for what
    the preset will demonstrate
  • Open up the file
  • Each row represents a motor, indicated by the number in the furthest left hand column
  • Fill in rows with the desired preset values for every motor
  • Once finished, make sure to save the file AS A CSV before closing it (even if it says there will be errors, there will not be and we need a CSV format in order to parse the data)
  • You should now be able to select this preset when browsing from the ‘Presets’ tab

Fixing Common Errors

Homing Issues

  • Issue: Sometimes, a few of the motors will not home when they are needed to. Solution: On the ‘Define Motors’ tab, select the ‘Off and Reset Button’. Then go through the steps for activating and defining the motors again and then try to home again. This should help fix the issue.
  • Issue: The GUI crashes or does not seem to respond for an undetermined reason. Solution: On the Studio5000 visualization, toggle the Clear_Motor_Error bit which should clear any lingering errors from past crashes.

Studio5000 Helpful Tips

Each individual piston is in reality controlled by Studio5000. The GUI is just a more efficient way to call Studio5000 and handle the pistons collectively. Studio5000 is also responsible for any quantitative and qualitative feedback given on the motion of the pistons. This section highlights useful tips on how to find and use Studio5000 features.

Visualization Tool

As stated above, by navigating to the file Tasks > Main Task > Wave_Control and double clicking on A_1_Control a user can see a diagram of the motors that are being used. Since this information is also being reflected in our GUI, it is not vital that this is always open while running the machine; however it contains many of the parameter values that may be useful to examine.

Parameter Values

Parameter information can be found by digging through the Studio5000 visualization tool. There are some predetermined limitations on parameters that can be found by clicking on the ‘Parameter Details’ button on the ‘Define Motors’ tab. Exceeding these limitations is often why the pistons will fault and fall to the bottom, and we advise being aware of these limitations when trying to push the machine.

LinMot-Talk Tips

LinMot-Talk is the software that configures, tracks, and controls position and other settings on the motors.

You must login to LinMot-Talk for each motor you want to edit and specify the motor number at the end of the IP address 192.168.001.xxx, where the last three digits are the motor number plus two. For example, to login for motor 29, the last three digits of the IP address are 031.

Once logged in, you can edit motor settings with the Motor Wizard. Go to Drive > Motor Wizard to adjust motor settings. Step 5/9 in the Motor Wizard is particularly helpful because it sets up the feedback loop for position control. Specifying the parameters based on the water depth for each experiment on each of the motors will improve adherence to the defined curve at higher speeds.

Uploading a Curve

While logged in, you can also upload new curves in LinMot-Talk by following the steps in this video by Raphael Provosty (rprovosty@gmail.com).

Database

The analytics of every run will be saved in a MongoDB database called wavemaker_db and can be found in new_GUI > database > database.py. The main purpose of the database is to create a training dataset in order to be used for a Machine Learning model in the future. We aim for this model to aid in fixing the motor synchronization problem: naturally occurring mismatch between pistons positions due to differences in resistances and water level forces.

Querying a Run

Each entry will have the following fields:

  • date: string “mm/dd/yyyy”, date for the run
  • interval_label: float, interval separation
  • time_label: float, total time recorded
  • data: dictionary, {“motor 1”: {“t1”: displacement1, …}, … , “motor n”: {…}}. This is a double dictionary with all the data on displacement (actual position – expected position) of each motor in each point of time according to the interval and time configuration. The bigger dictionary has keys representing each motor. The value of each key is another dictionary containing times as keys and displacement as values.

In order to query the results from VS Code, the function query_database(optional str: query) must be used. This function will return all findings within the general_collection in wavemaker_db database. A new python script must be ran:

  • Open VS Code
  • Make sure the database is running. To verify, a command shell named mongodb_run should be open. If not, open it from the Desktop.
  • Create a new .py file with the following content
  • The following example will query all runs on September 3rd, 2023:
    • from database.py import query_database
    • results = query_database({“date”: “09/03/2023”})

To query results from Mongo Shell, we must call the mongosh command from a command shell and operate from there. Follow these steps:

  • Open a command shell (terminal)
  • Call “C:\Users\”
  • You should get some information on the mongo shell and now you should be in it.
  • From the mongo shell call the following commands:
    • use wavemaker_db
    • db.general_collection.find(optional query)
  • These commands should return all entries from the general_collection. In case the names have been modified, apply them to the commands accordingly.

Current Database Settings & Updating Database

All settings are already hard coded into the codebase and saved in MongoDB Compass. The data is the following:

  • Database name: wavemaker_db
  • Collection name: general_collection
  • Server name: “mongodb://127.0.0.1:27017/”

However, in case a new collection is needed, here are the steps to be followed in order to create one:

  • Open VS Code
  • Create a new .py file with the following content:
    • from pymongo import MongoClient
    • client = MongoClient(“mongodb://127.0.0.1:27017/”)
    • db = client.{database_name}
    • collection = db.{collection_name}
  • If you put new database and/or collection names, it will correspondingly create these.
  • Run the script
  • Go back to database.py and update the functions with the new database and collection names ON BOTH FUNCTIONS
  • Save
  • Go back to regular use of GUI

Testing

Testing is fairly straightforward and is done directly in VSCode and the terminal.

  • Enter the codebase on VSCode
  • Go into the “Testing” directory to see what testing files you’d like to see
  • cd into testing directory in terminal
  • To test run command “python -m pytest [file name]” in the terminal

At this point you will see what tests are passing and which ones are failing. From VSCode you can also add new tests for added test coverage using pytest syntax.

Other Info