IRIS EAGLE SDK User manual

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 1
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
EAGLE SDK
QuickStart Guide
Version 1.0.0

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 2
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
CONTENTS
Introduction ........................................................................................................................................................ 3
Warning ........................................................................................................................................................... 3
Connect the Eagle and motor ......................................................................................................................... 3
USB Connectors ............................................................................................................................................ 4
Power Lugs..................................................................................................................................................... 4
RJ45 Connectors .......................................................................................................................................... 4
Back-power..................................................................................................................................................... 4
Demo Firmware ................................................................................................................................................. 4
Custom Firmware ............................................................................................................................................. 8
Cloning the EagleSDK2.0 Repository ........................................................................................................ 8
Setting Up the Development Environment ............................................................................................... 9
Programming the Eagle Board ................................................................................................................ 10
EagleSDK Libraries..................................................................................................................................... 11
ic4_library................................................................................................................................................. 11
modbus_client ........................................................................................................................................ 11
orca600_api ............................................................................................................................................. 11
GUI_Panels .............................................................................................................................................. 11
Signals ...................................................................................................................................................... 11
GPIO Section ................................................................................................................................................... 12
LIST OF FIGURES
Figure 1: Connecting the Eagle to a PC and Motor ..................................................................................... 3
Figure 2: IrisControls4 Startup page .............................................................................................................. 5
Figure 3: Two motor example, with 1 motor connected on port 1 .......................................................... 6
Figure 4: Splitting the Orca Data cable between PC and Eagle communications ................................ 8
Figure 5: Accessing Git Bash .......................................................................................................................... 9
Figure 6: Board Selection .............................................................................................................................. 10
Figure 7: Preferences settings ..................................................................................................................... 10
Figure 8: Auto Re-Connect in settings menu ............................................................................................ 11
Figure 9: GPIO protection circuit ................................................................................................................. 12
Figure 10: Example circuit ............................................................................................................................ 12
Figure 11: Header association with pin number ....................................................................................... 13

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 3
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
INTRODUCTION
The SDK firmware runs on a Eagle controller development board and is meant to provide
communication with up to 3 Orca Series motors using MODBUS protocol which has been
abstracted through the Orca API (Actuator object). It includes libraries to allow development of
custom firmware for motor position and force control as well as creating custom GUI interfaces.
There are examples included to show basic use as well as tutorials with an associated guide.
IrisControls4 is the Windows-based user-interface application used by IrisDynamics Ltd. Devices
to present controls and data over USB.
Warning
Be aware that the shaft or motor will move during operation. This firmware will cause the motor to
create forces and motion. Ensure the shaft and motor are mounted in a safe location and are not
in danger of hitting people or property.
CONNECT THE EAGLE AND MOTOR
For a basic setup, connect the motor’s power and ground to an external 24-48 V power supply,
connect the data cable to UART port 1 on the Eagle controller and connect the Eagle controller to
a PC via the micro USB cable. Additional setup options can be found in the SetUpDiagrams
document.
Figure 1: Connecting the Eagle to a PC and Motor

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 4
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
USB Connectors
To connect from the Eagle to a PC you will need to use either a micro USB type B or a USB type B
cable.
A Micro USB will provide power and ground to the board from the PC. If using the isolated USB port
with a USB B cable, the board will require another 12-24 V power source connected to the power
lugs on the Eagle Board.
Power Lugs
The power lugs on the Eagle Controller can take an input voltage of 12 - 24 V. The supply can be
an AC-DC converter or a battery system.
Once the Eagle has been programmed with appropriate firmware it may be operated without a
usb connection to a PC/IrisControls if it is powered through the power lugs and no GUI or serial
communications are desired.
If using an Orca Series 24 V motor, the motor's power and ground cables may be connected to
the screw terminals opposite the power lugs.
RJ45 Connectors
In Figure 1, the RJ connectors are labelled with UART port 1 and port 2. If the third location above
port 1 is populated this is UART port 0. These will be associated with the motor name and the
uart channel in the code.
Back-power
The motors in some circumstances will act like generators, this can result in current being fed
backwards to power lugs. Typically the level of back-power is low and power supplies or batteries
can accommodate this. In situations where shaft or stator speeds get very high, some power
supplies may go into protection.
DEMO FIRMWARE
There will be a demo program loaded to the board which can be viewed by opening the
IrisControls4 windows application. Run IrisControls4. exe, which can be found in the IrisControls4
folder of the repository.
A drop-down menu above the Connect button will allow you to select the COM port of the Eagle
board.
The settings menu can be accessed through the gear button. This is where the baud rate for serial
communications between the IrisControls app and the device communicating with it is set. The
Eagle controller will connect with any selected baud rate. (The Orca motor required 460800).

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 5
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
Figure 2: IrisControls4 Startup page
When connection has been established, two graphs will appear in the IrisControls4 window.
These graphs, labeled with the corresponding data ports on the Eagle board, show the position
and force that the motor is sensing. When a motor is connected and has no errors, the title of the
graph will turn green. Ports with no connected motor will have a grey title, and motors which have
errors will show a red graph title. Under the graph, there are five values and a slider.
 Voltage supplied to the motor, in Volts
 Temperature of the motor, in Celcius
 Power being used by the motor, in Watts
 Error codes, flags indicating the error present, multiple errors can be presented in
combination, for example error 320 would be temperature and power exceeded
o Configuration Errors - 31
o Force Clipping - 32
o Temperature Exceeded - 64
o Force Exceeded - 128
o Power Exceeded - 256
o Shaft Image Failed - 512
o Voltage Invalid - 1024
o Comms Timeout - 2048
 Frequency of communications between the Eagle and the Orca motor

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 6
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
The slider shows the amount of force being sensed by the motor, either through the motor
exerting a force on the shaft or from an external force.
Figure 3: Two motor example, with 1 motor connected on port 1
The following buttons will appear beside the graph.
Enable: The enable button will be blue when the Eagle port is enabled (i.e. the Eagle is pinging the
port for a motor response), and will be grey when disabled (no communications on the port). This
button can be clicked to change the status.
Zero Position: the zero position button sets the current position of the shaft as the new zero
position. When the zero position button is clicked, the Position slider will reset to zero as well to
prevent a sudden jump in force.
Clear Errors: When there is an error with the motor, the error code will show under the graph, the
title will be red, and the motor will not exert any force until the error is resolved. If the error is not
persistent, it can be cleared by clicking the clear errors button. However, if the motor senses that
the error has not been resolved, the error will still be there. The errors will also get cleared by
entering "Sleep" mode.
Sleep: On start up the motor will be in "Sleep" mode and the sleep button will be disabled. If in a
different mode the motor will return to "Sleep" mode when clicked. When the motor is in sleep
mode, the button will become disabled. A motor in "Sleep" mode will produce an electrical braking

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 7
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
force (should feel a slight damping effect when moving the shaft). While in this mode, the
Position and Force sliders are disabled.
Position: When clicked, the position button will move the motor to "Position" mode, this will also
enable to Position slider. In position mode, the user can use the Position slider to change the
target position of the shaft in the motor. The user can also enter a position number in the field
beside the slider. This field is measured in micro-meters. When position mode is enabled and the
shaft is at the given position, the motor will work to keep the shaft at that position by means of
PID control in the motor. In this example a small amount of proportional control is being used
which will make the motor feel like a spring that is centered around the target position the value
of the controller can be adjusted through the code.
Force: When clicked, the force button will move the motor to "Force" mode, this will also enable to
Force slider. In force mode, the user can use the force slider to change the force exerted by the
motor on the shaft. Positive and negative force can be used to change the direction of the shaft
movement. The user can also specify force by entering values into the field beside the force
slider.
Other prebuilt examples can be found in the builds folder and can loaded using the teensy.exe
program.
1. Open the Teensy.exe application.
2. Drag the desired firmware image (a .hex file) from the \builds folder onto the Teensy.exe. The
filename should show up in the window.
3. Press the "Auto" button on Teensy.exe so that it is bright green.
4. Plug the Eagle into the PC by USB (and power if using the isolated USB port).
5. Press the button on the bootloader board to start programming.
It is possible to simultaneously view the Eagle IrisControls4 GUI and the Orca IrisControls GUI by
opening a second instance of IrisControls4.exe. The provided splitter is required for this setup as
seen in Figure 4. For the motor to connect to IrisControls, the baud rate must be set to 460800
and the Orca COM port must be selected from the drop-down menu.
Please see the Orca Motor Reference Manual for full details regarding the Orca GUI which can be
found in the User Manuals section of https://www.irisdynamics.com/downloads/

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 8
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
Figure 4: Splitting the Orca Data cable between PC and Eagle communications
CUSTOM FIRMWARE
Cloning the EagleSDK2.0 Repository
If you do not have GIT Bash on your machine, download and install it from https://git-
scm.com/downloads
Iris Dynamics’ public code repositories can be found on GitHub at the following link:
https://github.com/orgs/IrisDynamics/repositories?q=&type=public&language=&sort=
In the file directory on your computer where you’d like to clone a repository, right click and select
'Git Bash Here'.

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 9
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
Figure 5: Accessing Git Bash
To clone this repo with all included submodules type the git bash command:
git clone https://github.com/irisdynamics/EagleSDK_2.0 --recurse
Note: If you miss the --recurse at the end, the submodule folders will be empty, you can populate
them by running the following command in the git bash window
git submodule update --init
Setting Up the Development Environment
To compile and build the firmware for the Eagle, the Arduino environment must be set up. Install
Arduino (version 1.8.19): https://www.arduino.cc/en/software . Ensure that Arduino is installed
through the Arduino website and not through the Microsoft Store. Teensyduino is used to upload
the compiled code to the Eagle. Install Teensyduino (version 1.56):
https://www.pjrc.com/teensy/td_download.html
Find the code file you’d like to load to the Eagle, example projects are available in the
“EagleSDK_2.0/source” folder. Double click the .ino file in the project folder to open the Arduino file.
Before compiling the target board will need to be set: Tools->Board -> Teensyduino -> Teensy
3.2/3/1.

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 10
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
Figure 6: Board Selection
Then the sketchbook location must be set in the preferences to the location of the EagleSDK_2.0
folder. While in the preferences windows check the Display line number box for a better
programming experience.
Figure 7: Preferences settings
Programming the Eagle Board
In the Arduino application, click the checkmark button in the top left corner to compile the code.
Compilation status will print in the console at the bottom of the page (i.e. compilation has finished,
compilation fails, error messages).

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 11
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
Once the code has compiled successfully, the Teensyduino app will open. Ensure the Auto button
in the Teensyduino app is light green, meaning Automatic Mode is on (click it to turn on/off
Automatic Mode).
Click the upload button on the Eagle bootloader board. The Teensyduino app will show a
programming progress bar.
The GUI associated with the loaded firmware can be viewed from the IrisControls4.exe application.
To make development smoother, press the gear on the top right of the console to enter the settings
menu and check the Auto Re-Connect button
Figure 8: Auto Re-Connect in settings menu
The existing examples can be edited, or you can use the tutorial guide to get started with your
custom project.
EagleSDK Libraries
The include libraries provide many tools for your custom development
ic4_library : IrisControls4 API, GUI elements and serial communications with IrisControls4.exe,
more info here : https://wiki.irisdynamics.com/index.php?title=IrisControlsAPI4_Overview
modbus_client : Modbus communications, contains the Actuator object (Orca API), more
information can be found here: https://www.irisdynamics.com/downloads/ in the Orca API
Reference Manual under the user manuals section.
orca600_api : Memory map associated with the Orca motor, more information can be found here:
https://www.irisdynamics.com/downloads/ in the Orca Series Motor Reference Manual under the
user manuals section.
GUI_Panels : Premade combinations of GUI elements for common feedback/functionality. More
information on using these can be found in the EagleSDK Tutorial Guide
Signals : Various signal types that can be used for example to create position or force targets, see
the Signal_Panel and Tutorial 5 for more information on using this library.

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 12
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
GPIO SECTION
A GPIO section is provided with an unpopulated protection circuit. To direction connect from the
input to the pin, the two resistor pads can be shorted. Depending on the application resistors,
capacitor, LEDs, and diodes can be used to populate the circuit.
Figure 9: GPIO protection circuit
Figure 10: Example circuit
The numbers and letters are associated with pins on the microcontroller, ground and +5 V are
also made available. The pin mode will need to be configured in the firmware code to use a
certain channel. The pin number is in the center of the section. For example, channel 1 is
associated with pin D15/A1, channel E is associated with pin D17/A3.

Eagle SDK
QuickStart Guide
Contact [e-mail] for additional information pg. 13
Iris Dynamics Ltd. Victoria, British Columbia T [phone] F [phone] www.irisdynamics.com
Figure 11: Header association with pin number