1. Do not share user accounts! Any account that is shared by another person will be blocked and closed. This means: we will close not only the account that is shared, but also the main account of the user who uses another person's account. We have the ability to detect account sharing, so please do not try to cheat the system. This action will take place on 04/18/2023. Read all forum rules.
    Dismiss Notice
  2. 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 Now a Download Plan!
  3. 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
  4. 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. Do not follow these rules can lead to permanent exclusion from this website: Read the forum rules.
    Are you a company? Read our company rules

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

Discussion in 'Tutorials and Tips by the Developer' started by yobuddy, Mar 17, 2023.

  1. yobuddy

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

    Joined:
    Feb 9, 2007
    Messages:
    5,133
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    47,906Coins
    Ratings:
    +5,027 / 16 / -0
    SimTools v3 - Interface Plugin API documentation

    Here are things that are already done for you in this Interface API!
    · All the saving and reloading of configuration files is done for you!
    · You make one plugin, but it magically can be used for up to 6 interfaces!
    · All output throttling is handled by SimTools!
    · A lot of other functions are already all setup for success. (Like when the user is able to save 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 v3.

    1. Interface Settings – Basic settings for the new Interface Plugin.
    2. The Form – Form Creation and Structure variables.
    3. Interface Subs – 6 subroutines to control the engine

    Let’s get started!
    Example Plugins: (Serial Interface is used in this example)
    Serial_InterfacePlugin_Example.zip

    FYI: You do not need to edit the built in section that look like this:
    upload_2023-3-17_13-44-58.png
    Doing so will probably only make things not work as they should

    1) Open the plugin by unzipping and clicking on “InterfacePlugin.sln”.
    2) Then double click on “InterfacePlugin.vb” in solution explorer.
    upload_2023-3-17_13-45-5.png

    Step 1) Basic settings for the new Interface Plugin
    upload_2023-3-17_13-45-12.png

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

    _RequiresInitialization- Does this plugin require a startup routine, or 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.


    Step 2) The Form
    A) Double Click on “UserControl_Settings.vb” in solution explorer.
    upload_2023-3-17_13-45-30.png

    We are now going to build our form for this Interface Plugin. Place the needed controls on the form for your Interface plugin. (The back color of the form should be transparent)

    (Here is a pic of the Example plugins GUI.)
    upload_2023-3-17_13-45-38.png

    B) Now let’s setup our structure for this form. (Right Click on “UserControl_Settings.vb” in solution explore and select View Code)

    We need to add ‘1’ variable to the structure for settings we want to save on the form.
    Notice there are ‘15’ controls on the form, but we only need one variable for the 3 radio buttons. So, I’m going to need 13 variables in my structure.

    This is what I did.
    upload_2023-3-17_13-45-53.png

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

    Set_AxisNames
    Let’s teach the plugin how to set the axis names
    upload_2023-3-17_13-46-11.png

    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…
    upload_2023-3-17_13-46-28.png


    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…
    upload_2023-3-17_13-46-43.png


    ClearSettingsWindow
    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…
    upload_2023-3-17_13-47-14.png


    'Optional - Paint the plugins form to match the skin
    PaintSkin
    We can use sub to ‘paint’ out plugins form to look like the rest of the current skin selected.
    upload_2023-3-17_13-47-22.png

    CheckSaveButton
    Let’s teach our Plugin how to tell when there is enough data on the form to successfully run our Plugin.
    upload_2023-3-17_13-48-16.png

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

    Simply call the CheckSaveButton() routine whenever the value changes for all of the controls that are used in then CheckSaveButton routine.
    upload_2023-3-17_13-48-25.png

    Step 3) Interface Subs – 6 subroutines / functions to control interface
    upload_2023-3-17_13-48-31.png

    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.
    upload_2023-3-17_13-48-36.png

    ShutDown - If you need to do anything when the interface shuts down, you can do so here.
    upload_2023-3-17_13-48-43.png

    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
    upload_2023-3-17_13-48-49.png

    GameStart - This 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.
    upload_2023-3-17_13-49-3.png

    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 these 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”)
    upload_2023-3-17_13-49-14.png


    GameStop -
    Here you can teach Game Engine how to shut down your Interface Plugin. In this example I am 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.
    upload_2023-3-17_13-49-47.png

    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 simply copy and paste all the extra code I made into here for a little cleanup and the end of the build.
    upload_2023-3-17_13-49-54.png



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




    How to Compile the Plugin

    Double Click on “My Project”
    upload_2023-3-17_13-50-56.png

    With the “application” tab is selected, name the Interface DLL as follows: InterfaceName (without spaces) + _ InterfacePlugin.

    So then for this example we get ‘Serial_InterfacePlugin. Use this name for both the ‘Assembly Name’ and the ‘Root Namespace’ as in the picture below.
    upload_2023-3-17_13-51-6.png

    Right click on InterfacePlugin in the solution explorer and select Build!
    upload_2023-3-17_13-51-13.png

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

    Use can use the Interface Plugin Tester to verify that your new plugin is working correctly.​
    Interface_PluginTester.zip
    upload_2023-3-17_13-51-21.png



    ~ Add a Banner ~
    Simply Zip the ‘dll’ file - Example: MyPlugin_InterfacePlugin.zip
    Next add a banner to the zip file, the banner should be a 390 x 128 pixels jpg picture named MyPlugin_Banner.jpg


    Congratulations!!
    Your new Interface Plugin is complete!
    Now install it into SimTools 3.0 and test out your work!
    • Winner Winner x 1
    Last edited: Mar 17, 2023
  2. yobuddy

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

    Joined:
    Feb 9, 2007
    Messages:
    5,133
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    47,906Coins
    Ratings:
    +5,027 / 16 / -0
    reserved...
  3. Ayad

    Ayad Dr.

    Joined:
    Apr 11, 2022
    Messages:
    21
    Occupation:
    surgeon
    Location:
    Iraq
    Balance:
    - 357Coins
    Ratings:
    +1 / 0 / -0
    My Motion Simulator:
    2DOF, 3DOF, DC motor, Arduino
    I am so confused ,this is so hard to learn ,the 2 version easy to write interface, Do I need to do all this to use the simtool ,I don't know how to test my simulator ,I upgrade license to pro version and still not know how to work with and how to connect with my simulator ,HELP PLEASE , am so tired I start to leave my project and quit the job ,I formate the computer ,upgrade the license ,I read and read but seems to be hard to work with the first time was very excited ,the simulator work good the just when try to use 2 seprated 24v power to each motors and every things goes apart THE drivers start to burn the potentiometers strat to read one side and not the other side ,and every things goes apart ,I try to restrat for the bigining and nothing changed and i start to thinking about quiting the simulator
  4. noorbeast

    noorbeast VR Tassie Devil Staff Member Moderator Race Director

    Joined:
    Jul 13, 2014
    Messages:
    20,460
    Occupation:
    Innovative tech specialist for NGOs
    Location:
    St Helens, Tasmania, Australia
    Balance:
    144,596Coins
    Ratings:
    +10,741 / 52 / -2
    My Motion Simulator:
    3DOF, DC motor, JRK
    No you do not need to learn or know anything about the information in this thread, as it is for members who want to create plugins for SimTools 3.

    If you are having problems then please detail the issue(s) on your build thread, so there is information about your project for context.
  5. Frank1999

    Frank1999 New Member Gold Contributor

    Joined:
    May 16, 2020
    Messages:
    15
    Balance:
    33Coins
    Ratings:
    +3 / 0 / -0
    My Motion Simulator:
    4DOF
    I'm trying to port my V2 interface plugin to V3, and I'm currently encountering some problems:
    1. Communication should be normal, can start up(all axes move to center point) and shut down (all axes return to origin), but it seems that the motion data is not sent correctly, there is a small vibration of low frequency in all axes. But in the interface setup, there is no response to move the axes.
    2. The plugin is installed offline and cannot be found in the plugin manager, nor deleted on .
    Any ideas? Please help.
    20230418173103.jpg 20230418173047.jpg 20230418172956.jpg
  6. yobuddy

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

    Joined:
    Feb 9, 2007
    Messages:
    5,133
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    47,906Coins
    Ratings:
    +5,027 / 16 / -0
    Looks like you have some doubles loaded, let's fix that problem below in question 2.

    Because your Interface plugin did not come from a repo, it will not show up in a repo (plugin manager).
    But you can simply close v3, open "C:\Users\YourUserFolder\AppData\Local\SimTools3\InterfacePlugins" and simply delete your test plugin. Then restart v3.

    You can also update your test interface plugin this way too, simply replace the dll with a newer one for testing. When your finished testing, you can export your new interface plugin, and then delete it from the folder above. And once your new interface plugin is finished and uploaded to a repo, it will be removable from the repo like normal.

    Take care,
    yobuddy