Difference between revisions of "1. Setup: DLL Project, Control XDL & the AHAS Lua file"

Latest revision as of 09:56, 25 June 2018

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).

[edit] 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.

Allegro Hand Application Studio\userControllers

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

[edit] Create New DLL Project

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

[edit] Create Project

In the File dropdown menu, click New > Project.

File > New > Project

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.

C:\Program Files (x86)\SimLab\Allegro Hand Application Studio\userControllers

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.

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.

Click Finish to create your new project.

[edit] Add Files

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

myAHController (right click) > Add > New Item...

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.
Leave the location as the default. Click Add to add the file to your project.

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

myAHController.cpp
myAHController.h
myAHControllerCmd.h

You can see these new files in your Solution Explorer.

[edit] 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.

myAHController (right click) > Properties

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:

[edit] [Debug Configuration]

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

[edit] [Release Configuration]

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

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

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.

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

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

[edit] 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:

1. 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.
2. 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.

[edit] 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.

C:\Program Files (x86)\SimLab\Allegro Hand Application Studio\bin\controls

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

[edit] 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.

<?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>

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.

[edit] 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.

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)
...

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.

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.

Our edited Lua looks like this:

print(RoboticsLab.version())
 
aml = "models/Etc/AllegroHand/AllegroHandL.aml"
controlXDL = "controls/myAHController.xdl"
...
...
...

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

[edit] 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.

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

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

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

Close the Properties window.

[edit] Finally, the Controller!

We created our Visual Studio (VS) project earlier in the tutorial with three files:

myAHController.cpp
myAHController.h
myAHControllerCmd.h

Goals:

1. Make your own dll that doesn't do anything.

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.
You might be failed to launch your application.
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.
RoboticsLab Programming Guide PDF - Page 139, Section 4. Custom Control Algorithms

[edit] myAHController.h

#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

[edit] myAHControllerCmd.h

#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

[edit] myAHController.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);
}

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

2. Allegro Hand Joint Position Control