View source for 1. Setup: DLL Project, Control XDL & the AHAS Lua file ← 1. Setup: DLL Project, Control XDL & the AHAS Lua file

'''We do not support AHAS Tutorials anymore. Please try Windows Projects or Linux Projects.'''

To implement your own control algorithm for the Allegro Hand is relatively simple once the intial framework has been established. This tutorial will guide you through the steps necessary to create your own controller plugin and access it via Allegro Application Studio.

'''''Note:''' This tutorial assumes you have Allegro Application Studio and Visual Studio 2008 (Service Pack 1) installed. If you have not yet installed Allegro Application Studio, please see the pages [[Allegro Application Studio (Installation)]] and Allegro Application Studio (User Manual).''

==Create User Controllers Folder==

Start off by creating a folder called '''''userControllers''''' within the Allegro Hand installation directory. The Visual Studio projects can be stored anywhere, but if you match the project folder location seen in this tutorial, all following file paths specified will be correct.

<pre>Allegro Hand Application Studio\userControllers</pre>

Within this folder, we will create a new Visual Studio DLL project.<br>

==Create New DLL Project==

Open up Visual Studio (VS) 2008. Again, it is necessary to have Service Pack 1 installed to use SimLab products.<br>
It is necessary to open VS 2008 with Administrator Privilege.

===Create Project===

In the ''File'' dropdown menu, click ''New'' > ''Project''.

<pre>File > New > Project</pre>

In the ''New Project'' window, select ''Win32'' under ''Project types'' and choose the ''Win32 Console Application'' template. In the ''Name'' field, choose a name for the controller. We recommend Its name as '''''myAHController''''' for the project name. In the ''Location'' field, choose the newly created ''userControllers'' folder in the ''Allegro Hand Application Studio'' directory.

<pre>C:\Program Files (x86)\SimLab\Allegro Hand Application Studio\userControllers</pre>

<br>[[image:newProject.jpg|400px]]<br><br>

'''Create directory for solution''' should be unchecked. Click ''OK'' to continue.

When greeted by the ''Win32 Application Wizard'', click ''Next >'' to configure the new project.

<br>[[image:applicationWizard.jpg|400px]]<br><br>

You will then be presented with a few options. Change the ''Application type'' to ''DLL'' and, under ''Addition options'', choose to create and ''Empty project''.

<br>[[image:applicationSettings.jpg|400px]]<br><br>

Click ''Finish'' to create your new project.

===Add Files===

In the ''Solution Explorer'' (likely in a pane on the left side of VS) you should see your new project, ''myAHController''.<br>
Right click the '''bold''' project name (not Solution 'myAHController' to add a new item to the project.

<pre>myAHController (right click) > Add > New Item...</pre>

<br>[[image:addFile.jpg|400px]]<br><br>

If you click ''Visual C++'' under in the ''Categories'' pane, you will all of the available templates. Choose the template ''C++ File (.cpp)'' and name is '''''myAHController'''''.<br>
Leave the location as the default. Click ''Add'' to add the file to your project.

<br>[[image:addCpp.jpg|400px]]<br><br>

Repeat the ''Add New Item'' process two more times to add two ''Header Files (.h)'' to the project titled '''''myAHController''''' and '''''myAHControllerCmd'''''.<br>
By this time you should have added three files to the project:<br>

<pre>
myAHController.cpp
myAHController.h
myAHControllerCmd.h
</pre>

You can see these new files in your ''Solution Explorer''.

<br>[[image:solnExplorerWFiles.jpg|300px]]<br><br>

===Project Properties===

To compile the project with all the proper dependencies and behaviors, the several properties must be set prior.

In the ''Solution Explorer'' (likely in a pane on the left side of VS), right click the '''bold''' project name (not Solution 'myAHController' (1 project)), and select ''Properties''.

<pre>myAHController (right click) > Properties</pre>

<br>[[image:Properties.jpg|400px]]<br><br>

Within the project ''Property Pages'' window, you will see a pane of expandable groups. The following properties must be edited before compiling a control plugin for Allegro Hand Application Studio:

====[Debug Configuration]====
<pre>
Configuration Properties > C/C++ >
  1. General > Additional Include Directories: ..\..\include;
  2. Preprocessor > Preprocessor Definitions: WIN32;_DEBUG;_WINDOWS;_USRDLL;MYAHCONTROLLER_EXPORTS;R_EXPORTS
 
Configuration Properties > Linker >
  3. General > Output File: ..\..\bin\controls\$(ProjectName).dll
  4. General > Additional Library Directories: ..\..\lib;..\..\lib\BHand;
  5. Input > Additional Dependencies: rMath_9d.lib rxControlSDK_9d.lib libBHand.lib
</pre>

====[Release Configuration]====
<pre>
Configuration Properties > C/C++ >
  1. General > Additional Include Directories: ..\..\include;
  2. Preprocessor > Preprocessor Definitions: WIN32;NDEBUG;_WINDOWS;_USRDLL;CONTROL_ALLEGROHAND_EXPORTS;R_EXPORTS
 
Configuration Properties > Linker >
  3. General > Output File: ..\..\bin\controls\$(ProjectName).dll
  4. General > Additional Library Directories: ..\..\lib;..\..\lib\BHand;
  5. Input > Additional Dependencies: rMath_9.lib rxControlSDK_9.lib libBHand.lib
</pre>

<br>[[image:Props1.jpg|400px]]<br><br>

The only new preprocessor definition should be ''R_EXPORTS''.<br>
This allows the DLL file to be exported properly for use with Allegro Hand Application Studio.

<br>[[image:Props2.jpg|400px]]<br><br>

The output file specified is the DLL file control plugin. This is output the the ''bin\controls'' directory where AHAS can access it. The additional library directories contain general and Allegro Hand specific libraries included with AHAS.

<br>[[image:Props3.jpg|400px]]<br><br>

The additional dependencies include the RoboticsLab Math and Controls SDK libraries, along with the Allegro Hand library.

<br>[[image:Props4.jpg|400px]]<br><br>

Press ''Apply'' to save the changes then press ''OK'' to close the ''Properties'' window.

==Create Controller XDL==

And XDL file must be created to link AHAS and the controller DLL exported by the VS project. This file has two main purposes:
# It provides the path to the controller DLL
#* This allows the user to easily switch to a new controller by simply changing the path. Neither the controller file code nor the AHAS files need to be edited to switch the controller.
# Variables can be added to this file and accessed by the controller.
#* This allows properties like gains to be edited without recompiling the controller code.

===New XDL===
For the purpose of separating user created control plugins from the stock AHAS controller, we will create a new XDL file to be used with a new AHAS file. For future user created controller plugins, you need only edit the path to the control plugin DLL within this XDL. You will not need to create a new XDL and AHAS file for each control plugin.

Start by navigating to the controls folder of your AHAS installation folder.

<pre>C:\Program Files (x86)\SimLab\Allegro Hand Application Studio\bin\controls</pre>

In this folder you will find a file entitled ''control_AllegroHand_L.xdl''.<br>
Copy and paste the file in the same folder and rename it ''myAHController.xdl''

===Edit myAHController.xdl file===

The contents of the file can be edited in any text editor but an editor meant for html editing, like Notepad++, is suggested.

Open the XDL file in whatever text editor you choose and you will see the following.

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<DLL xmlns="http://www.simlab.co.kr/2008/XDL" name="control_AllegroHand" path="control_AllegroHand.dll" type="USER_CONTROL" ver="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.simlab.co.kr/2008/XDL XDL.xsd">

  <credit address="SimLab Co., Ltd." creator="Sangyup Yi" date="August 22, 2012" description="control Allegro Hand" email="seanyi@simlab.co.kr"/>

  <property name="handNumber" value="1"/>

  <property name="myName" value="hand1"/>

  <property name="whichHand" value="Left"/>

</DLL>
</syntaxhighlight>

In this XML code, the fields of interest are set apart from the rest of the code. In your XML file, there will likely be one long line with most of the information in it. In this XML file we must change the fields ''Name'', the controller name(myAHController), and ''Path'', the path to the DLL file(myAHController.dll) exported by myAHController VS project.

'''''Reminder:''' The path is just the name of the DLL file because the DLL will export to the same folder as the XDL file, controls.''

Last, we will check the field titled ''whichHand''. This field is referenced by the controller to determine whether to control a left or right hand. If you are using an Allegro RIGHT Hand, this field should say '''''Right'''''. If using a LEFT hand, this field should say '''''Left'''''. Save the changes and close the text editor.

==AHAS Lua File==

The AHAS environment is created using a ''Lua'' file located in the ''bin\controls'' directory of the AHAS installation directory. To take advantage of the new controller that we will create, we will create a new Lua file. This allows us to roll back to the stock AHAS environment if we encounter any problems.

Find the ''Lua'' file called ''AHAS_L.lua'' and copy and paste it to the same folder. Rename the file '''''myAHController.lua'''''. Open ''myAHController.lua'' to see the following code.

<syntaxhighlight lang="lua">
print(RoboticsLab.version())

aml = "models/Etc/AllegroHand/AllegroHandL.aml"
controlXDL = "controls/control_AHAS_L.xdl"

sysname = "hand"
T0 = HTransform.new(Rotation.new(), Vector3D.new(0, 0, 0))
hand = RoboticsLab.createSystem(aml, sysname, T0)
...
</syntaxhighlight>

To access our new controller, ''myAHController.xdl'', we must change what is necessary in this ''Lua'' file.
Change '''controlXDL = "controls/control_AHAS_L.xdl"''' to '''controlXDL = "controls/myAHController.xdl"''' in the fourth line.

For now, we will leave all of the buttons in place for later use.

<br>

'''''Note:''' In this file, we are loading the '''AllegroHandL.aml''' which is the model for the virtual left hand. If your XDL '''whichHand''' field says '''Left''', then this is correct. If the '''whichHand''' field says '''Right''', you should load '''AllegroHandR.aml''.'''

<br>

Our edited ''Lua'' looks like this:

<syntaxhighlight lang="lua">
print(RoboticsLab.version())

aml = "models/Etc/AllegroHand/AllegroHandL.aml"
controlXDL = "controls/myAHController.xdl"
...
...
...
</syntaxhighlight>

We will continue to edit this ''Lua'' as the tutorial progresses.

==AHAS Shortcut==

To make our life easier in the future, we will create a shortcut directly to this newly created ''myAHController.lua'' simulation load file.

First, navigate to ''Allegro.exe'' in the AHAS ''bin'' folder. 

<pre>C:\Program Files (x86)\SimLab\Allegro Hand Application Studio\bin\Allegro.exe</pre>

Right-click ''Allegro.exe'' and select ''Create shortcut'' in the menu. Likely, you will be forced to create the shortcut on ''Desktop'' due to write privileges in the ''Program Files'' directory. If not, create the shortcut there, then move it to the ''Desktop''. Rename the shortut to something like '''''myAHController''''' so that you can tell it apart from the original AHAS shortcut.

This shortcut will open AHAS as normal giving you the option to select a hand and a CAN device. To link directly to a certain simulation, right-click the shortcut and select ''Properties'' from the menu. In the ''Shortcut'' tab of the ''Properties'' window, locate the ''Target field''. Edit the ''Target'' field so that the second argument is the new ''Lua'' file path, ''controls/myAHController.Lua''

<pre>
Original Target: "C:\Program Files (x86)\SimLab\Allegro Hand Application Studio\bin\Allegro.exe"
New Target:      "C:\Program Files (x86)\SimLab\Allegro Hand Application Studio\bin\Allegro.exe" controls\myAHController.lua
</pre>

<br>[[Image:shortcut.jpg|300px]]<br><br>

Close the ''Properties'' window.<br>

==Finally, the Controller!==

We created our Visual Studio (VS) project earlier in the tutorial with three files:
<pre>
myAHController.cpp
myAHController.h
myAHControllerCmd.h
</pre>

'''Goals:''' 
# Make your own dll that doesn't do anything.
<br>

The following code is the basis for your AHAS control plug-in. Please paste this code into the respective files, compile, then click the shortcut on the desktop to launch your custom AHAS application. You can now begin to develop your Allegro Hand controller.<br>
You might be failed to launch your application.<br>
In that case, download [[File:AllegroHandAml.zip]], unzip and paste them in ''Allegro Hand Application Studio\bin\models\Etc\AllegroHand folder''.

For more information, please read the comments below and reference the ''RoboticsLab Programming Guide''.<br>
[http://simlab.dyndns.org:9000/AllegroHandWiki/images/2/29/RoboticsLab_BegProgrammingGuide.pdf RoboticsLab Programming Guide PDF] - Page 139, Section 4. ''Custom Control Algorithms''

===myAHController.h===
<syntaxhighlight lang="cpp">

#ifndef __MY_AH_CONTROLLER_H__
#define __MY_AH_CONTROLLER_H__
 
#include <list>
#include "rControlAlgorithm/rControlAlgorithm.h"
#include "BHand/BHand.h"
 
// myAHController inherited from algorithm interface class
class REXPORT myAHController : public rControlAlgorithmEx
{
public:
	myAHController(rDC rdc);
	~myAHController();
 
	virtual void init(int mode = 0);
	virtual void update(const rTime& t);
	virtual int  command(const short& cmd, const int& arg = 0);
 
private:
	virtual void _readDevices();
	virtual void _writeDevices();
 
	virtual void _compute(const rTime& t);
 
	void _arrangeJointDevices();
 
 
private:
 
	// algorithm variables go here
};
 
#endif

</syntaxhighlight>

===myAHControllerCmd.h===
<syntaxhighlight lang="cpp">

#ifndef __MY_AH_CONTROLLER_CMD_H__
#define __MY_AH_CONTROLLER_CMD_H__
 
#include "rCommand/rCmdManipulator.h"
 
// These commands will be fed into command()
// and can be used to envoke certain actions
// by the robot. Allegro Application Studio
// will use these to interface with the
// cotroller plug-in.
#define BH_NONE		(RCMD_USER + 0)
#define BH_HOME		(RCMD_GO_HOME)
// #define BH_ONE		(RCMD_USER + 1)
 
#endif

</syntaxhighlight>

===myAHController.cpp===
<syntaxhighlight lang="cpp">

#include "myAHController.h"
#include "myAHControllerCmd.h"
 
 
myAHController::myAHController(rDC rdc) 
:rControlAlgorithmEx(rdc)
{
	// initialize all the class member variables
}
 
myAHController::~myAHController()
{
}
 
void myAHController::init(int mode)
{
	// create hand and find devices
	// arrange joint devices function will be called here
	// set degrees of freedom
	// make sure all vectors are the correct size and
	// set all of the components to zero before computing
}
 
void myAHController::_arrangeJointDevices()
{
	// find and store all motors and encoders
}
 
void myAHController::update(const rTime& t)
{
	// Evokes _readDevices(), _estimate(), _reflect(),
	// _compute(), _writeDevices() in turn by default.
}
 
void myAHController::_readDevices()
{
	// read sensors
}
 
void myAHController::_writeDevices()
{
	// write to actuators
}
 
void myAHController::_compute(const double& t)
{
	// Computes control inputs
}
 
int myAHController::command(const short& cmd, const int& arg)
{
	// Handles user-defined commands according to cmd.
	// Further information can be retrieved from the second argument.
 
	// The variable cmd will be received from Allegro Application Studio
	// and will be used to envoke hand actions
	return 0;
}
 
rControlAlgorithm* CreateControlAlgorithm(rDC& rdc)
{
	 return new myAHController(rdc);
}

</syntaxhighlight>

Execute the myAHController.exe in desktop folder. You will see virtual AllegroHand and an apple.<br>
The buttons on the left don't work because you've replaced original control_AllegroHand.dll file to your own dll.<br>
Please move onto our next tutorial to learn how to control the joints of the Allegro Hand.<br>

[[2. Allegro Hand Joint Position Control]]
[[Category:Programming Guides]]