1. For downloading SimTools plugins you need a Download Package. Get it with virtual coins that you receive for forum activity or Buy Download Package - We have a zero Spam tolerance so read our forum rules first.

    Buy Download Package Now!
  2. Do not try to cheat our system and do not post an unnecessary amount of useless posts only to earn credits here. We have a zero spam tolerance policy and this will cause a ban of your user account. Otherwise we wish you a pleasant stay here! Read the forum rules
  3. We have a few rules which you need to read and accept before posting anything here! Following these rules will keep the forum clean and your stay pleasant here. Do not following these rules will lead to permanent exclusion from this website: Read the forum rules.

Tutorial How to write an Interface Plugin for SimTools 2.0 - API documentation

Discussion in 'Tutorials and Tips by the Developer' started by yobuddy, Jul 16, 2016.

  1. yobuddy

    yobuddy Well-Known Member Staff Member Moderator SimTools Developer SimAxe Beta Tester Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    Feb 9, 2007
    Messages:
    3,062
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    32,377Coins
    Ratings:
    +3,142 / 10 / -0
    SimTools v2 - Interface Plugin API documentation

    Here are things that are already done for you in this Interface API!
    • All the saving and reloading of files is all done for you!
    • All profiling is done. The user can create and reload profiles from your plugin!
    • You make one plugin, but it magically can be used for up to 6 interfaces!
    • All output throttling is handled by Game Engine by default! (but can be overridden if needed)
    • Allot of other functions are already all setup for success. (Like when the user is able to save there valid settings.)

    There are 3 sections of any new Interface Plugin that needs to be completed in order to produce a compatible Interface Plugin for SimTools 2.0.
    1. Interface Settings – Basic settings for the new InterfacePlugin.
    2. The Form – Form Creation and Structure variables.
    3. Interface Subs – 6 subroutines to control the engine

    Let’s get started!
    Example Plugins: (MemMap used in this example)
    Serial - Example Interface Plugin.zip
    Network - Example Interface Plugin.zip
    MemMap - Example Interface Plugin.zip

    Interface Backdrop pic (should you need it.)
    Background.jpg

    1) Open the plugin by unzipping and clicking on “InterfacePlugin.sln”.
    2) Then double click on “InterfacePlugin.vb” in solution explorer.
    P1.jpg


    Step 1) Basic settings for the new Interface Plugin
    P2.jpg

    _PluginAuthorsName - The name, or names of people that have worked on the plugin.
    If someone sends you a plugin to edit/add-on too, please just add your name with a coma like this “Original Author, Your Name”.
    _InterfaceName – The Name of the Interface (Please don't use the word 'Interface' in the name)
    _Requires_Restart - Does this plugin require a restart with New or Removed settings?
    For example: to run a startup routine on the actuator (with an optical encoder usually) in order to find home.

    What Interfaces are we enabling this plugin for?
    _Enable_Interface1 - Is this plugin enabled for Interface 1 in Game Engine?
    _Enable_Interface2 - Is this plugin enabled for Interface 2 in Game Engine?
    _Enable_Interface3 - Is this plugin enabled for Interface 3 in Game Engine?
    _Enable_Interface4 - Is this plugin enabled for Interface 4 in Game Engine?
    _Enable_Interface5 - Is this plugin enabled for Interface 5 in Game Engine?
    _Enable_Interface6 - Is this plugin enabled for Interface 6 in Game Engine?

    In most cases you can leave these all set to True. But if you find a need, you can tell Game Engine what Interfaces you plugin will be enabled for.


    Step 2) The Form
    A) Double Click on “UserControl_Settings.vb” in solution explorer.
    P3.jpg

    We are now going to build our form for this Interface Plugin. Place the needed controls on the form for your Interface plugin. (Do not remove the Save Button)
    (Here is a pic of the Example plugins GUI.)
    P4.jpg

    B) Now let’s setup our Structure for this form. (Double click on “InterfacePlugin.vb” in solution explorer)
    We need to add ‘1’ variable to the structure for each control on the form.
    Notice there are ‘6’ controls on the form, but I’m going to just keep track of the ‘Output – Type’ selected, so I will only need one variable for the 3 radio button controls. So I’m going to need 4 variables in my structure.

    This is what I did.
    P5.jpg

    C) Now let’s teach the form a few tricks! – (Right Click on “UserControl_Settings.vb” in solution explore and select View Code).

    P6.jpg

    LoadFormFromStructure()
    Teach the Form how to fill itself from the Structure data.
    (See example plugin for more detail)
    Example
    txt_Name_interface.txt = _InterfaceSettings._Name
    And so on for all controls on the form…

    LoadStrutureFromForm()
    Teach the Structure how to read the Form data.
    (Just the opposite from the sub above) (See example plugin for more detail)
    Example
    _InterfaceSettings._Name = txt_Name_interface.txt
    And so on for all variables in the Structure…

    P7.jpg

    Clear_AxisAssignments()
    Teach the Form how to reset itself.
    (Resetting the structure is not needed – just the form)
    Example
    txt_Name_interface.txt = “”
    And so on for all controls on the form…

    CheckSaveButton()
    Let’s teach our Interface Plugin how to tell when there is enough data on the form to successfully startup and run our Plugin.

    Since one radio button is always selected, we only need to make sure the other 3 controls contain valid data for saving and running out interface. Here you can see than I am checking that they have valid data for Update Rate, Interface Name and the Output bits. Only when the user selects or enters data for all 3 of these controls can they save there settings.

    Simply call the CheckSaveButton() routine when ever the value changes for all the controls that are used in then CheckSaveButton() routine. (I had 3 in this interface)
    P8.jpg

    Step 3) Interface Subs – 6 subroutines / functions to control interface
    P9.jpg

    StartUp()
    If you need to do anything before you interface plugin can startup, you can do so here. In the example I am loading the Ascii chart into a variable array for faster output when the engine is running.

    ShutDown()
    If you need to do anything when the interface shuts down, you can do so here.

    Initialize()
    If you using optical encoders, or anything that needs to ‘find home’, you can have it do that during the startup of Game Engine here

    P10.jpg

    GameStart()
    The tells game engine what to do when the game starts up. Here I am making sure that all values are set to default values and setting it into a memory space.
    I also load the user’s settings for the engine to run.

    P11.jpg

    Game_SendValues()
    Here you get access to the SimTools RAW values. You will receive a number between -1 and 1 (with 0 being the center). This makes scaling the output values to whatever you need very easy! That’s all I’m doing here, re-formatting the RAW output values from Game Engine to the selected output type & bit-range. And then I send the values to the memory mapped file.

    Game Engine automatically throttles the output rate the mandatory _OutputRateMs in the structure you built earlier. We have this values tied to a control on the form. If you didn’t want this to be user editable, you could set the value of the output rate with GameStart() above. (Like this “MyForm._InterfaceSettings._OutPutRateMS = 10”)

    GameStop()
    Here you can teach Game Engine how to shutdown your Interface Plugin. In this example I am an essentially sending a centering command to the interface, waiting to make sure the external device gets the data, and then disposing of the memory mapped file.

    Place any extra code need that makes this Interface plugin work in this next section. This way if you ever have to work on the plugin again, you know where everything is located at! I simple copy and paste all the extra code I made into here for a little cleanup and the end of the build.
    P12.jpg

    You do not need to edit sections that look like this:
    P13_NoEdit.jpg
    Doing so will probably only make things not work as they should


    That’s it!
    Let’s compile your new plugin!​

    How to Compile the Plugin
    Double Click on “My Project”
    P14.jpg

    Make sure the “application” tab is selected. Now name the Interface DLL as follows: InterfaceName (without spaces) + _ InterfacePlugin. So for this example we get ‘MemoryMap_InterfacePlugin. Use this name for both the ‘Assembly Name’ and the ‘Root Namespace’ as in the picture below.
    P15.jpg

    Right click on InterfacePlugin in the solution explorer and select Build!
    P16_Compile.jpg

    Your new Interface plugin can now be found in the folder;
    ExamplePluginFolder\InterfacePlugin\InterfacePlugin\bin\Release\MyPlugin_InterfacePlugin.dll

    Run ‘PluginValidator.exe’ in the same folder to validate your new plugin.
    P17_Compile.jpg


    Congratulations!!
    Your new Interface Plugin is complete!
    Now install it into SimTools 2.0 and test out your work!​
    • Informative Informative x 4
    • Like Like x 1
    • Useful Useful x 1
    Last edited: Apr 6, 2018
  2. speedy

    speedy Well-Known Member SimTools 2.0 Beta Tester

    Joined:
    Feb 1, 2012
    Messages:
    1,190
    Location:
    Alexandria , Egypt
    Balance:
    7,381Coins
    Ratings:
    +1,259 / 9 / -0
    My Motion Simulator:
    3DOF, AC motor, Arduino, Motion platform
    definitely very good ... :cheers
  3. AlexinChina

    AlexinChina Member

    Joined:
    Sep 2, 2015
    Messages:
    71
    Location:
    China
    Balance:
    272Coins
    Ratings:
    +6 / 1 / -0
    My Motion Simulator:
    2DOF, DC motor, Arduino, Motion platform
    How can I download the SimTools 2.0, I find SimTools 1.3 only.
  4. noorbeast

    noorbeast VR - The Next Generation Staff Member Moderator SimTools 2.0 Beta Tester

    Joined:
    Jul 13, 2014
    Messages:
    11,763
    Occupation:
    Innovative tech specialist for NGOs
    Location:
    St Helens, Tasmania, Australia
    Balance:
    91,407Coins
    Ratings:
    +7,686 / 37 / -2
    My Motion Simulator:
    3DOF, DC motor, JRK
    SimTools 2.0 is still in closed beta testing, it has not been released yet.
  5. AlexinChina

    AlexinChina Member

    Joined:
    Sep 2, 2015
    Messages:
    71
    Location:
    China
    Balance:
    272Coins
    Ratings:
    +6 / 1 / -0
    My Motion Simulator:
    2DOF, DC motor, Arduino, Motion platform
    I am look forword to SimTool2.0, it's plugin looks more concise than SimTool1.3
  6. AlexinChina

    AlexinChina Member

    Joined:
    Sep 2, 2015
    Messages:
    71
    Location:
    China
    Balance:
    272Coins
    Ratings:
    +6 / 1 / -0
    My Motion Simulator:
    2DOF, DC motor, Arduino, Motion platform
    How can I do to become a SimTool2.0's tester
  7. noorbeast

    noorbeast VR - The Next Generation Staff Member Moderator SimTools 2.0 Beta Tester

    Joined:
    Jul 13, 2014
    Messages:
    11,763
    Occupation:
    Innovative tech specialist for NGOs
    Location:
    St Helens, Tasmania, Australia
    Balance:
    91,407Coins
    Ratings:
    +7,686 / 37 / -2
    My Motion Simulator:
    3DOF, DC motor, JRK
    It is up to the SimTools developer @yobuddy to determine what testing is needed, on what range of sims/hardware.
  8. siemenson

    siemenson New Member

    Joined:
    Feb 19, 2016
    Messages:
    10
    Location:
    Hangzhou Zhejiang China
    Balance:
    224Coins
    Ratings:
    +1 / 0 / -0
    My Motion Simulator:
    2DOF, Arduino
    Good document, and I'm looking forward to simtools 2.0.
    • Like Like x 1
  9. Blame73

    Blame73 Yet it moves!

    Joined:
    Nov 6, 2014
    Messages:
    1,136
    Location:
    Italy
    Balance:
    8,047Coins
    Ratings:
    +988 / 1 / -0
    My Motion Simulator:
    2DOF, DC motor, Arduino, Motion platform
    Hey @yobuddy , have you also got the C# version? I don't like VB :oops:
  10. value1

    value1 Nerd Staff Member Moderator SimTools Developer SimAxe Beta Tester Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    Jan 9, 2011
    Messages:
    2,044
    Location:
    Zug, Switzerland
    Balance:
    4,534Coins
    Ratings:
    +2,882 / 10 / -1
    My Motion Simulator:
    2DOF, DC motor, JRK, Joyrider
    In principle you can code the plugin-dll in any language of your choice. Just translate the given VB code in C#
  11. Blame73

    Blame73 Yet it moves!

    Joined:
    Nov 6, 2014
    Messages:
    1,136
    Location:
    Italy
    Balance:
    8,047Coins
    Ratings:
    +988 / 1 / -0
    My Motion Simulator:
    2DOF, DC motor, Arduino, Motion platform
    Of course one should do as you say, it was just my laziness talking.
    Let's wait for ver. 2.0 so I could start coding. In the worst case 12 days to go! Someone said November, right?
  12. ferslash

    ferslash Active Member

    Joined:
    Feb 8, 2011
    Messages:
    464
    Balance:
    4,519Coins
    Ratings:
    +165 / 2 / -0
    guys, i think that one thing that could make a huge difference with simtools 2, is that the writing of a game pluging could be made ease... i tryed to see the documentation of game plugins in simtools 1 and i got a headage :D
    (i know this thread is about interface plugin, but, please consider an ultra easy game pluging making)

    fer
  13. noorbeast

    noorbeast VR - The Next Generation Staff Member Moderator SimTools 2.0 Beta Tester

    Joined:
    Jul 13, 2014
    Messages:
    11,763
    Occupation:
    Innovative tech specialist for NGOs
    Location:
    St Helens, Tasmania, Australia
    Balance:
    91,407Coins
    Ratings:
    +7,686 / 37 / -2
    My Motion Simulator:
    3DOF, DC motor, JRK
    Unfortunately how data is extracted from a game for motion varies, from the game developers making it directly accessible to having no direct access at all, other than by memory hooks, so it is not easy to have a generic simple way to make plugins.
  14. Blame73

    Blame73 Yet it moves!

    Joined:
    Nov 6, 2014
    Messages:
    1,136
    Location:
    Italy
    Balance:
    8,047Coins
    Ratings:
    +988 / 1 / -0
    My Motion Simulator:
    2DOF, DC motor, Arduino, Motion platform
    It's like saying that heart operations should be easier so that more people could do them.
    There are difficult things to do in life, programming is not only about 'Hello World' stuff
    • Agree Agree x 3
    • Funny Funny x 1
  15. ferslash

    ferslash Active Member

    Joined:
    Feb 8, 2011
    Messages:
    464
    Balance:
    4,519Coins
    Ratings:
    +165 / 2 / -0
    @Blame73, it is just a good wish... but everything can be easier, just a little easier :D:D:D

    best regards

    fer
  16. obobo

    obobo Active Member

    Joined:
    Nov 8, 2016
    Messages:
    248
    Location:
    France
    Balance:
    1,218Coins
    Ratings:
    +76 / 1 / -0
    My Motion Simulator:
    2DOF, DC motor, Arduino
    For it to be simpler, devellopeurs should have a unified API to make this information accessible!
  17. yobuddy

    yobuddy Well-Known Member Staff Member Moderator SimTools Developer SimAxe Beta Tester Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    Feb 9, 2007
    Messages:
    3,062
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    32,377Coins
    Ratings:
    +3,142 / 10 / -0
    There is nothing else I can slim down or make easier I'm afraid. :think
    I have spent more than a year making it simpler.
    More that half of the needed code is all done for you behind the scenes.
    (see top of page for some details)

    All of the api's that have a function that does the same thing as a function in another api are labeled the same. :thumbs
    So LoadFormFromStructure() does the same thing in the Interface API as it does in the Axis Assignments API.
    Once you see an example plugin, things will surly make more sense.

    Take Care! :cheers
    yobuddy
  18. obobo

    obobo Active Member

    Joined:
    Nov 8, 2016
    Messages:
    248
    Location:
    France
    Balance:
    1,218Coins
    Ratings:
    +76 / 1 / -0
    My Motion Simulator:
    2DOF, DC motor, Arduino
    I acknowledge that you do a great job (I can not)
    I have not yet recovered plugin for my simu that is not yet finished
    I would look at the structure of the plugin at this time
  19. Cyberklutz

    Cyberklutz New Member

    Joined:
    Jun 22, 2012
    Messages:
    10
    Balance:
    35Coins
    Ratings:
    +1 / 0 / -0
    Would be great if you could help out re developing an interface plugin for Phidget Cards. Any possibility?
  20. yobuddy

    yobuddy Well-Known Member Staff Member Moderator SimTools Developer SimAxe Beta Tester Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    Feb 9, 2007
    Messages:
    3,062
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    32,377Coins
    Ratings:
    +3,142 / 10 / -0
    @Cyberklutz
    I love Phidget Cards!
    I use them for computerized gardens!

    The one problem with any device like this thou is it requires that the PC be the brains of the operation.
    With an Arduino, we simply send it a "move to" location and the card does the rest.
    I would call this an "Intelligent controller" as it has its own 'brain' onboard for independent operation from the PC itself.
    In other words, if the PC were to crash, the arduino would just stop receiving "move to" command and stop moving"

    But with a Phidget, the PC would have to constantly read a potentiometer to see where the motor is and them set the correct speed etc.
    So the PC itself become the "brain" of the interface and does a lot more than just accept "move to" commands from the PC.
    And if the PC were to crash, you could go for one wild ride!
    This is what I would call an "Un-Intelligent controller".
    the K8055 is another example of a "Un-Intelligent controller".

    Don't get me wrong thou, its not that it wont work, its just that there are better ways I believe.
    yobuddy
    • Funny Funny x 1
    • Informative Informative x 1