Machsupport Forum
Mach Discussion => Mach Screens => CVI MachStdMill (MSM) => Topic started by: DaveCVI on July 18, 2010, 04:52:45 PM
-
[Update 8-3-2010: The document that was previously attached to this post has been removed. The information it contained is no longer relevant and has became obsolete as of the MSM Beta 3 release. Please see chapter 14 of the MSM user manual for updated information.]
Hi Everyone,
I've started this thread is in response to a question about how to modify MSM button actions.
As I said in that thread, I believe adults should be treated as such and so my philosophy is usually going to be to let people have as much rope as they like to hang themselves with... In exchange I insist that people also understand that I am not here to "Save you from the hangman's rope". :o
Before you decide to modify the beta test MSM package, please give this really serious consideration:
If you need to modify MSM to get special system functionality, you really should probably wait until MSM is out of Beta testing.
“Danger: There be Dragons here!”
Remember that this is the MSM beta software.
The beta program is intended to test and debug MSM and the dev rev of Mach3.
The beta program is not intended to provide support for people to modify MSM.
No offense is meant to anyone, but this is the MSM beta test program and I can not afford to volunteer time to support or debug things that happen as the result of user modifications.
I frankly very, very, much prefer that users not modify MSM at all during the beta program.
You proceed solely at your own risk by reading further! The rules are no whining and no complaining from this point forward…
Finally, please do not use these instructions to modify MSM and then start a forum thread with “why doesn’t my custom script work? All I changed was…" I may not be predisposed to pay much attention to such a thread...
OK Charlie, you really want to drink the soda don't you?
[for those outside the US, see http://en.wikipedia.org/wiki/Willy_Wonka (http://en.wikipedia.org/wiki/Willy_Wonka) to understand this cryptic reference.]
To get in more trouble, see the document attached to this post.
[ UPDATE 7-23-2010 - The info in the doc below reflects the state of affairs as of MSM beta 1 (and 2). This is an area of internal implementation that is going to get a pretty major redesign. The methods for modifying an MSM button are very likely to change significantly within the the next couple of weeks. ]
Dave
-
Dave,
Compliments on the ease of reading/understanding.
-
Wow, Dave,
An amazing piece of explanation when a "Don't even THINK about editing button script in the beta." would have almost sufficed!! You have a way with words in this technical writing arena, that's a fact. I read the MSM manual cover to cover today, hilighter and red pen in hand, just for entertainment and to lay a foundation for actually putting the screen set into use. I'll skim thru once more then start putting some of the stuff to use, probing and tool setting in particular. It's a marvelous piece of work, and from my experience with the screen set so far, that's equally as amazing. I don't mean to "fawn", but this is great stuff.
-
Aw shucks..... :)
Seriously, it does feel good that people like it!
Dave
-
Dave, why do you Expand to get the actual code instead of a RunScript?
-
Ron,
Your simple question really requires a very long narrative to fully explain. I’m going to try to keep to the short version…
MSM uses both #expand and RunScript. This of course begs the question: Why one vs. the other? The short answer is they each have different limitations… and “history”.
The Mach script language is a Basic dialect (nothing can be done about that now), and you inherently get all the pros and cons that come with programming in Basic. A basic script naturally wants to be a totally self contained widget. That doesn’t match very well with a project that requires you place code into 100s of buttons….
As the project progressed, I really started to dislike parts of the code and I began to really seriously worry about maintainability and support issues.
What I really needed to be able to do in a cypress script was to define an arbitrary function or subroutine, have just one source copy of it, and be able to just use it from any script, with all the normal parameter passing mechanisms that Basic languages have.
I researched the Cypress engine interfaces and realized that this should be pretty easy to do. The cypress engine includes all the hooks needed to do this. Cypress anticipated this need and it’s part of the Cypress product. Naively, I contacted Brian to see if I could cajole him into “turning this on”…. Long story short - due to the way the Cypress Engine was spliced into Mach way back in the mists of time, this turned out to be essentially impossible (or at least way more work that it was reasonable to do inside Mach3 V3).
So we turned to discussing what could be done with more reasonable amounts of effort, within a useful time frame.
The first mechanism I tried was RunScript. It already existed but not been exposed as an interface.
1) Code() and MCode files -> RunScript()
Prior to RunScript, the only container available to hold code that you want to call from multiple places was a M123.m1s file – and the only way to “Call or run” it was with the Code() API. This was designed to allow simple user defined Mcodes. It was not intended as a general “subroutine call mechanism”.
There are some major problems with using Code() as a script subroutine mechanism:
a) The Mach Code() interface uses the GCode engine to “run” the M123 file (after all a M123 file is really a Mcode). When you think about this, you come to realize that the name of the Code() interface is a bit misleading, it would be more accurate to name it GCode() or even something like InsertGCodeIntoQueue().
b) The need to invoke the gcode engine to run script code that does not really have anything to do with gcode is messy. It can also buy you a host of problems as a side effect (remember all the problems that occurred in earlier versions of mach when Code() changed from a sync construct to an async construct?).
c) The restriction to M123 files for names is a maintenance nightmare. You get lots of little files that are numbered. Not a good maintainable programming style.
Like everyone else, I had used this mechanism in MSM as it was the only game available (when all you own is a hammer, all problems look like a nail).
The first use I made of RunScript was to remove all uses of Code(“M123”). That was a significant improvement and removed a lot of side effect problems.
While doing that, Brian and I had many long conversations about potential ways to pass parameters to RunScript(). Again what should have conceptually been easy, turned out to be really hard. Passing parameters by name was not something I was going to get given how the Cypress was spliced in.
…but I had to have some parameters as I had used the P, R words with the Code() API to do “parameter passing”. The Mcode “calls” I was replacing already used simple parameters.
What to do? You use the tools you have at hand. (I’ve come to think of programming scripts in mach to be an exercise in ancient programming techniques. I pretend I’m a character in a time travel story that got sent back to the 1960s to program. Once you decide to go with the flow your stress level goes way down…. ).
I invented what is frankly a workable kludge: MSMRunScript(). This is an MSM internal wrapper for RunScript(). It uses MSM globals, coupled with implicit knowledge in a named script that will be “run” to implement “parameter passing”. Not elegant, but workable.
That’s not real pretty code. It’s Ok for internal MSM use, but not appropriate as an exposed API.
Key limitation: RunScript() has no parameter passing capability.
I also really needed to be able to define Constants in one place and use them in multiple scripts. I needed a way to stop maintaining multiple copies of the MSM DRO and LED lists etc.
Pre-Processing….
2) #Expand
Brian and I decided that it was probably possible to add simple pre-processing for Cypress scripts. Because this would be pre-processing (done before the code is handed to the cypress black box at run time), it avoids any need to modify the Cypress engine or to have to extend the Cypress language syntax.
As usual, this turned out to be more work than initially expected – Brian made it eventually happen (thanks again to Brian).
Pre-processing to include source code has some advantages over RunScript():
1) it allows implementation of header files – that helps a lot with code maintenance.
2) You can create common, readable code that has parameters – and all the type checking etc works as it is just basic source code.
In MSM I typically put the definition and body of a function in a source file, use it wherever I want to and then add a #Expand at the end of the upper level script to pull in the function definition.
3) The Syntax used for #Expand is a simple version of what C #include does. We included the < > and “ ” concepts from C pre-processing.
The < > form allows the location of the included scripts to not have to be hard coded into the scripts themselves. This is a feature that MSM takes advantage of.
Refer to the programmers manual for #expand. The < > features were also done with Wizards in mind. The < > path expansion for expand files is smart enough to know to look in a wizard name dependent location if a wizard is loaded ….
Clear as mud?
Summary:
Use the feature that is most appropriate for what you are trying to accomplish.
Generally
• MSM uses RunScript to replace Code(“M123”)
• MSM uses RunScript as a run time means to access script to be supplied after MSM ships (Example: this is done to “call” AutoToolChanger hardware specific code) w/o needing to alter the MSM script source.
• MSM uses #Expand to create header files and MSM code modules for internal MSM reuse.
IMPORTANT NOTE:
MSM has a lot of internally defined and internally used code interfaces.
Users are free to read the MSM code, learn from it, plagiarize from it. The license terms for the MSM package permit you to do this.
HOWEVER…. (This is important)….
Not a single line of the MSM code is guaranteed to be stable across releases. Each and every line of code is subject to change without notice in a future release of MSM.
MSM does not provide a set of guaranteed programming interfaces.
(There are a couple of candidates that may get documented and become supported “MSM APIs”, but as of the beta release there are no committed MSM API interfaces.)
MSM DRO, LEDS, variable names, in fact anything, can change at any time.
It is NOT SAFE to assume you can “use” an internal MSM interface from outside MSM.
Dave
P.S. I had to edit this post. Does anyone know why when I type in M followed by 3 x's the board turns it into M********* ?
I changed my references to M123...
[edit: 3 x's in a row is on the list of naughty words, so it automagically gets blanked out with stars... ;) scott]
-
Refer to the programmers manual for #expand.
Where is this manual?
-
Hi,
I know two sources for the current rev programmer's manual -
1) MSM installs a full set of manuals - so it's avail form the ref page of MSM
2) It's also avail from the machsupport documentation page
Here is a direct link
http://machsupport.com/docs/Mach3_V3.x_Macro_Prog_Ref.pdf (http://machsupport.com/docs/Mach3_V3.x_Macro_Prog_Ref.pdf)
FYI, Some people are also referring folks to a thread with an early draft that Ray did last year, that thread attachment does not have the additional info for the new APIs.
Dave
-
Can you actually put "#expand" in the index? I looked in their 3 times before posting and couldn't find it. Just noticed it under Script Pre Processing in the back.
Thanks.
-
Done for next rev.
Dave
-
Hi,
I have added the following edit to my post above re how to edit an MSM button....
[ UPDATE 7-23-2010 - The info in the doc below reflects the state of affairs as of MSM beta 1 (and 2). This is an area of internal implementation that is going to get a pretty major redesign. The methods for modifying an MSM button are very likely to change significantly within the the next couple of weeks. ]
The planned changes in this area are a key reason I don't advise people to modify MSM in early beta. I hate to see people have to do work over again - but that's the trade off if you choose to explore code modification methods at this time.
Frankly, the current beta makes it very hard to make mods that "stick" - an MSM beta install will overwrite most mods. In fact, MSM Beta 1-2 is so zealous about this that it is hard to add a button to the user exts page. It was known that this was the case when we started the beta.
In case you are wondering, the tension is between:
1) The need of the software vendor to be able to check user bug reports against known configurations of a product, and the need to push code updates to users.
2) support for user customizations.
MSM uses two concepts:
a) MSM "master files" (things that MSM installs and always updates when an install occurs) and
b) User modified **copies** of master files.
Effectively, MSM Beta 1-2, has the master concepts implemented, but not much of the user modified copy concepts.
The extent to which Mach allows users to customize (synonyms: "fiddle", "break" :D ) makes this no small challenge.
I'm working on this area now - but it will take a while to get the desired support for user mods implemented.
Dave