So you’re developing a THINC application to run on your Okuma THINC CNC. You’ve read the fine documentation in the Okuma Open API SDK, right?
If you’re new to THINC, and you haven’t yet read the documentation, you might have missed out on some helpful tips. So to get you started, here are seven very basic tips for THINC app development.
7. Remember to Init()
Before you use any THINC API functionality, you must create an instance of the
CMachine class (in the Data API namespace) and call its
Init method to initialize the library.
You only need to call it once, and once you’ve called Init(), you don’t even need to keep that instance of
CMachine around afterward.
But you do need to call Init() from your application’s main thread. The SDK’s
readme.md file suggests calling Init() from either the App startup event (WPF), or the Form Load event (WinForms).
To be safe, I usually make all THINC API calls from the same thread, but the documentation says that isn’t necessary. So remember to call Init() once when your application starts, and all is well.
6. Don’t hammer the API
You’re developing your new awesome THINC app, and you want to know the very moment when that common variable changes.
Did you know that a “moment” was originally a unit of time equal to about 90 seconds?
Our modern concept of a “moment” might be a little shorter, but while your code is looping calls to
GetCommonVariableValue, make sure that you’re not calling it more than once every 100 milliseconds.
That goes for any THINC API calls: the second thing in the documentation is a warning not to poll the API faster than once every 100 ms. Additionally, if you have plans to add your application to the MyOkuma App Store, their App Guidelines checklist has a check item for “Developer has confirmed that the app doesn’t poll the API faster than every 100 ms.”
If you think you need to poll THINC API faster than this, now might be a good time to remind you of the first thing in the documentation: “THINC-API cannot provide machine data in real-time.”
THINC API is a powerful tool, but if milliseconds matter to your application, it might not be the right tool for you.
5. Avoid the Startup folder
You want your application to run at startup, so you add a shortcut to your app to the Startup folder in the Start Menu. Or maybe you edit the Run entries in the Windows Registry.
Whoa, wait a second! Remember those MyOkuma App guidelines? Here’s another one:
Installer doesn’t put anything in the startup folder or the “Run” section of the registry. If auto-run is required, application registers with the THINC Startup Service.
What’s the THINC Startup Service? It’s a service that Okuma provides to monitor THINC API startup. You can register your application so that runs after THINC API is available.
So don’t just add a shortcut in the Startup folder. Use the THINC Startup Service to have a decent guarantee that the CNC is ready for your application to do its amazing thing.
4. Give me a (Alt-)Tab
I’ll keep quoting those MyOkuma App Guidelines because even if you have no plans to submit your app to MyOkuma, these are still solid guidelines.
And here’s a guideline that you might not otherwise think about:
Application is visible in the task-bar while its GUI is open. (is “alt-tab-able”)
This is important because most operators at an Okuma control will be working with a 15″ industrial touchscreen. When you have large fingers, it’s not always easy to hit a small target on the screen.
Don’t make it hard on the operator. Make sure you can Alt-Tab to your application. Similarly, here’s another similar consideration:
If a system tray icon is used, ANY click or touch will cause a menu to be shown OR the main GUI to be displayed / brought to front
Again, touchscreen. Even though the Okuma controls have a system tray icon that lets the operator toggle taps from left- to right-mouse-button, this too is hard to hit unless there’s a stylus available.
Make the menu for your app’s system tray icon activate for any kind of click or touch. And while you’re at it, make your menu items nice and big.
3. Errors? Log ’em
Continuing with the MyOkuma App Guidelines checklist, error logging is so important that Okuma devotes two checklist items to it.
Application implements time-stamped logging (at minimum at application start and when any errors occur)
Application log file location or access method is documented
This is a best practice for any software application, not just THINC. When a user in the field reports a problem with your application, the error log is going to be your main resource for figuring out what went wrong. So log errors and significant events, with timestamps.
(Incidentally, don’t forget that the THINC API itself will log all Set/Add/Cal method calls, and all exceptions thrown in the API.)
If you’re looking for a logging library, the readme recommends the TDG logginglibrary, which seems to be gone. It also mentions NLog, Log4Net, or Serilog, which are three common and well-documented .NET logging libraries.
2. Watch your resource usage
Okuma considers this one so important that it merits three items on its checklist: one for CPU usage, one for memory usage, and one for disk writes.
First, make sure CPU usage is reasonable. Okuma says your app’s CPU usage should not be constantly above 10%. (Intermittent peaks above 10% are ok.)
If you’re coming from a desktop software development background, remember that the CPU is inside a metal case that (due to its working environment) does not have good airflow.
CPU time is also shared not only with other Windows apps, but also the realtime CNC subsystem that gets first priority.
Second, watch for memory leaks. This is uncommon with .NET applications as long as you are properly disposing any unmanaged resources (such as files) when you finish with them.
Memory leaks can bring down the entire system, not just your application, so monitor your application in Task Manager, Process Explorer, or Performance Monitor, and make sure that memory usage and file handles don’t grow without bound.
Third, watch your disk usage. Okuma does not want to see daily disk writes exceeding 500 MB. Pay particular attention to error logging. An exception that occurs to a loop can quickly spam your error log with thousands of errors.
1. Make sure it works
This should be obvious, but make sure that your revolutionary new application actually works. Okuma has several items on the checklist that touch on this, for example:
- tester encounters no exceptions
- application exits without errors
- installs without error
But the key concept is that your application behaves the way it should. It installs, and installs dependencies if necessary. It starts up, runs without crashing, and exits without errors.
That’s All, Folks
Not really — that was seven broad categories, pulled from the Okuma Open API SDK readme, the MyOkuma App Guidelines, and the THINC API documentation itself.
There’s plenty more to know about THINC API, but if you’re just getting started with THINC App development, those are seven important things to remember.