MArmOS means Mechanical Arm Operating System and it is a script made to simplify the coding needed to properly control your mechanical arm. It allow to take any complex arm configuration and bind it on a ( X, Y, Z ) reference frame. Using MArmOS should make it way easier to control ground based machines like mobile mining rig, welding arms or cranes.​

MArmOS work by using a user-written expression I call "arm definition".
These definitions are used to represent the physical shape of your arm. (Like some kind of virtual model)
Those definitions are made out of elements called Hardwares.
An hardware can be a Solid shape, a Rotors Joint or a Pistons Joint.
When assembled properly, all these hardwares will allow MArmOS to take control of them and solve all the complex kinematic calculations.

The Script can be found here

This video describe step by step how to build a simple 4 DOF piston based connector crane using MArmOS.

Here are some examples of contraptions using MArmOS.
The Welding Crane
The Boom Truck
The Large Excavator
The Turrets

The ArmConfiguration() function is where you need to configure your contraption.
This function is called once when the script is compiled or when the game is loaded.

MArmOS works by using a user written configuration that represent the mechanical composition of a contraption.

These expression are made out of Harwares.
The idea is to look at your contraption and figure out how to translate it into Hardwares.

The basic setup only require you to define your hardware in order.
It is perfect for fast and easy general use configurations.
Note that the basic mode is sensible to the order in witch you declare your hardware, it will not consider parallelism and it can only manage a single arm.

Build your arm and set a unique names for all of it's components.

declare all components in order. MArmOS will automaticaly assemble a default arm with these.
e.g.
In this example, a DefaultArm is automatically created.

Defining the controller. It is an optional step because if none is defined, a default one will automatically be created with default values.
e.g.
Check the Controller class section for more details.

Rename a seat so it contains the ArmControllerKeyword it it's name. The default ArmControllerKeyword is "Arm Controller".

When defining a Part, you will need to find the right axis. Here is how to do so.
The axis system in MArmOS is following the right hand rule. The "X" is forward, "Y" is left and "Z" is up.


When defining axis for rotation, the right hand rule still apply. "X" is roll clockwise, "Y" is pitch downward and "Z" is yaw right to left.









If you want to reverse an axis, you just need to add a -. "X" become "-X", "Y" become "-Y" and "Z" become "-Z".


When working with rotors, the axis of rotation is in the direction the rotor head is facing.


Pistons uses the same logic.










Finally, to avoid making axis mistakes, Make sure that your arm is at it's Home position. Use the "GoHome" command for that.

Assembling your arm manually in MArmOS is just like a mathematical equation using " + ", " * " and " () ".
The " + " operator is used to represent two hardware attached in series. "end to end"
The " * " operator is used to represent two hardware attached in parallel. "side by side, working together"
Don't forget that, like in math, order of operations is a thing. "2+2*3 = 8, not 12 ... "
Because of that, you may want to use parenthesis in some cases. "(2+2)*3 = 12 yay!"

Here is a step-by-step example:
Build your arm.

Declare local variables for each components of your arm (including solid pieces).

Assemble all your pieces together like a mathematical equation using " + ", " * " and " () ".

Define your controller and tell it to control your arm instead of the default one. Check the Controller class section for more details.

Rename a seat so it contains the ArmControllerKeyword it it's name. The default ArmControllerKeyword is "Arm Controller".

Here is a map showing how MArmOS is structured.
Class in [] are planed but not done yet. edit: all classes in the map are done now.

The normal user should only need to use the following class:

• Rotor
  
• Piston
  
• SolidLG
  
• SolidSG
  
• Hydraulic
  
• UserControl

All other classes are for MArmOS's inner structure.

The UserControl class is the main controller in MArmOS. It is also the default controller. Its role is to convert all keyboard, mouse and arguments into Movement input for the arm.


(r/w) bool OnOff
(r/w) double YawSpeed
(r/w) double PitchSpeed
(r/w) double RollSpeed
(r/w) bool ReadKeyboard
(r/w) bool ReadMouse
(r/w) String ShipControllerKeyword
(r/w) Hardware ReferenceFrame
(r/w) cPose ConstantMovement
(r/w) cPose Target

void ExecuteCommand( String Argument )
void Update( String Argument )
void GoHome()
void SetHome()

When no controllers are defined on the arm configuration, a UserControl controller is automatically created with default values.
Those default values can be set in the Global settings section on page 9 of the script.

When false, the Controller will actively keep the arm from moving.
How fast you want to orient the arm on Yaw.
How fast you want to orient the arm on Pitch.
How fast you want to orient the arm on Roll.
If true, the controler will read the W, A, S, D, C and "spacebar" keys. This can depend on your game settings.
If true, the controler will read the mouse input plus the Q and E keys. This can depend on your game settings.
A keyword that your cockpit/remote control must contain for MArmOS to read its inputs.
The reference frame is what allow to have relative controls. You can set any Hardware object.
Using the UseArmAsReference parameter override this one.
A shortcut to automatically set the ReferenceFrame to Arm.
Using this parameter override this ReferenceFrame parameter.
A constant movement command that overlap the other inputs.
It can be set directly or by using the "Move" argument.
A target position. When set, the Arm will start moving toward it. If a keyboard or mouse input is detected, it get disabled.
It can be set directly or by using the "MoveTo" argument.
Whether or not the controller should start activated after compilation. If false, you'll need to activate it manually.
This method take a String containing one command.
If the command is valid, it will execute it. The name of the controller is not necessary here.

The Rotor class is a child of the Rotary Joint class. It inherit all of it's public variables.
It is a low level interface allowing Rotary to control a rotor ingame.







(R/W) String Name
(R/W) bool Override
(R/W) double SoftMinLimit
(R/W) double SoftMaxLimit
(R/W) double Offset // (rad)


The name of the rotor you want to control. MArmOS will search the grid for that rotor every seconds to be sure it still exist.
Whether or not the rotor should follow MArmOS's order. Set to true for manual control. The default value is false.
Allow to correct misalignment. The default value is 0.
Slow down the rotor before hitting its maximum angular limit. The default value is 1. higher is smoother.
Same as SoftMaxLimit but for Min.
Refer to the Rotary Joint class section for higher level details.

The Piston class is a child of the Linear class. It inherit all of it's public variables.
It is only an interface allowing Linear to control a piston ingame.
Note that a Piston object will only represent the extension of the piston. The unextended physical shape of the piston is not taken into account here.



(r/w) String Name
(r/w) double SoftMinLimit
(r/w) double SoftMaxLimit

The Name parameter refer to the name of the piston you want to control.
SoftMaxLimit slow down the piston before hitting its maximum limit. The default value is 1. Higher is smoother.
The same as SoftMaxLimit but for Min.
Refer to the Linear class section for higher level details.

The RotorWheel class is a child of the Linear class. It inherit all of it's public variables.
It is an interface allowing linear movements using a rotor and a wheel.
Note that a RotorWheel can only show a limited fidelity when it comes to show it's position. Slipping and others external movements can't be seen by the RotorWheel.

(r/w) Rotary Wheel
(r/w) double Radius // (m)
(r/w) int Direction

The wheel you want to control. It is usually a Rotor but can be anything from the Rotary family.
Radius of the wheel in meter.
Corrective factor to help with direction of rotation

The SolidLG class is a child of the Solid class.
Its only purpose is to declare a Solid using large grid dimensions. You can as well use the Solid constructor and multiply the number of blocks by 2.5


SolidLG does not expose any public variables.

Refer to the Solid class section for other details.

The SolidSG class is a child of the Solid class.
Its only purpose is to declare a Solid using small grid dimensions. You can as well use the Solid constructor and multiply the number of blocks by 0.5


SolidSG does not expose any public variables.

Refer to the Solid class section for higher level details.

The Hydraulic class is a child of the Rotary class. It inherit all of it's public variables.
It is a semi-low level interface allowing Rotary to control a Hydraulic settup ingame.
Note that when using Hydraulic, it is imperative to use the advanced definition. This is because the actuating bit is Seen by MArmOS as a fully indpendent arm to which the Hydraulic object is sending commands.
It can be hard to define an Hydraulic settup properly. I recomend getting used to simpler aspect of MArmOS before trying it.


(r/w) Hardware Actuator;

The actuating part (usually pistons but could be anything)
Basically MArmOS see it as an arm to which the Hydraulic object send velocity commands along the "X" axis.
The only movement considered in the calculations is the one along the "X" Axis. Hydraulic doesn't care about anything else.
Tangent distance between the pivot and the "Tail" of the actuator. See picture.
Normal distance between the pivot and the "Tail" of the actuator. See picture.
Tangent distance between the pivot and the "Head" of the actuator. See picture.
Normal distance between the pivot and the "Head" of the actuator. See picture.
Value to adjust the direction of rotation if needed.
Refer to the Rotary class section for higher level details.

The Rotary class is the virtual parent of all kind of rotating joints such as Rotors and Hydraulics.
It is the high level class that does all calculations involved by rotational kinematics.
It is also a child of the Hardware class and, as such, inherit all of it's public variables.

The normal user should never need to directly call the Rotary constructor but someone wanting to make a new child class could need it.

(R/W) double MaxSpeed
(R/W) double OriMode
(R ) double Angle // (rad)
(R/W) double dangle // (rad/ds)
(R/W) double Home // (rad)

The axis, around which, the joint will rotate. See the "Axis tips" section for details.
The OriMode parameter is a value between 0 and 1 that specify if the joint should favour the orientation of the end effector or it's position.
A Joint with OriMode set to 1 will follow the orientation inputs (usually given by the mouse) while a OriMode of 0 will prioritise position. Something in between will give a mix of both.
The Maximum speed the Joint should rotate.
The current angle. As seen by MArmOS. In (rad)
The angle derivation. Basically, Speed measured in (rad/ds). Divide by "dt" to get angular speed in (rad/s)
The Home position. The joint will move to that position if the GoHome command is used.
Refer to the Hardware class section for higher level details.

The Linear class is the virtual parent of all kind of linear joints such as pistons.
It is the high level class that calculate the linear kinematic.
It is also a child of the Hardware class and, as such, inherits all of its public variables.

The normal user should never need to directly call the Linear constructor but someone wanting to make a new child class could need it.

(R/W) double MaxSpeed
(R ) double Length // (m)
(R/W) double dLength // (m/ds)
(R/W) double Home // (rad)

The axis along which the linear joint will slide.
The maximum speed the joint will move.
The current Length of the Joint.
The current Length derivation of the Joint.
The Home position. The joint will move to that position if the GoHome command is used.
Refer to the Hardware class section for higher level details.

The Solid class is the parent of all kind of Solid shapes.
It basically is an unmoving piece.
It is also a child of the Hardware class and, as such, inherits all of its public variables.
Look at the tips bellow for usage details.

There are child constructors for Small and Large grids but you can as well use this one. It use meters instead of blocks.

Solid does not expose any public variables.

The length in meter along the "X" axis. See the Axis tips section for details.

The length in meter along the "Y" axis.

The length in meter along the "Z" axis.

You can see Solids as if your arm was some kind of skeleton made of joints and bones. The Solids are the bones linking each joints.

A solid part is basically the "3D distance" between the center of each Joints.
As an example, to define two rotors reparated by 3 large blocks(7.5m), you would actually need a 10m long Solid (4 blocks). See some examples.

Here is another example with a Piston. Pistons can be completely ignored since they have no rotary contribution.








Here is a special case of Rotor along the same axis as the arm. This example shows how axis of rotations of rotors are affecting Solids. It shows that while the ends of a Solid can move along the axis of a Rotor it must never cross it.








Here is how it should be done. Both pictures shows the same settup with two valid approaches. Both are correct and give the same result.











Refer to the Hardware class section for higher level details.

this part of the guide is not done yet.

The Controller class is parent of all controllers. It is the object that receive the movement inputs and make sure that the arm is properly folowing them.

The normal user should never need to directly call the Controller constructor but someone wanting to make a new child class could need it. Look for UserControl instead.

(r/w) String Name
(r/w) double Softness
(r/w) double Speed
(r/w) bool GoingHome
(r/w) Hardware Arm

void Update( String Argument )
void GoHome()

The arm that will be controlled.
The name of the controller. It is used to diferenciate controllers when sending argument commands.
The maximum speed your arm should go in (m/s)
How soft you want the controls
If true, every joints on the arm will move to their Home position.
It is set to false if a nonzero input is detected.
This is the method that run the controller. MArmOS automatically run it every cycles.
This method set the GoingHome variable to true.

Synopsis: ReadKeyboard On/Off/Toggle
Shortcut: -RK 1/0/-1
Description: Tell the controller to read keyboard inputs or not.
Synopsis: ReadMouse On/Off/Toggle
Shortcut: -RM 1/0/-1
Description: Tell the controller to read mouse inputs or not.
Synopsis: Move X Y Z [Yaw] [Pitch] [Roll]
Shortcut: -M X Y Z [Yaw] [Pitch] [Roll]
Description: Follow a linear motion forever.
Synopsis: MoveTo X Y Z [Yaw] [Pitch] [Roll]
Shortcut: -MT X Y Z [Yaw] [Pitch] [Roll]
Description: Follow a linear motion toward a specific point then stop.
Tip: You can use the PrintPosition command to get the actual position of your arm in a nice MoveTo format. This can be usefull to do sequences.
Synopsis: RelMove X Y Z [Yaw] [Pitch] [Roll]
Shortcut: -RelM X Y Z [Yaw] [Pitch] [Roll]
Description: Follow a linear motion relative to the Reference Frame.
Synopsis: PrintPosition [TextPanelName]
Shortcut: -PP TextPanelName
Description: Print the current position of the arm into a text panel. The printed format is the same as a MoveTo command to make automation easier.
Synopsis: ClearPanel TextPanelName
Shortcut: -CP TextPanelName
Description: Clear the content of a text panel.
Synopsis: Speed Value
Shortcut: -S Value
Description: Set the Speed parameter to a specified Value.
Synopsis: Softness Value
Shortcut: -SO Value
Description: Set the Softness parameter to a specified Value.
Synopsis: GoHome Speed
Shortcut: -GH Speed
Description: Tell all joints to go to their respective Home position. The Speed argument allow an approximated speed control of the movement.
Synopsis: SetHome
Synopsis: SetPartHome Value PartName
Description: Temporaly set the current Home of a rotor or a piston to a specific value. This can be useful when you want to do joint based movements.
Synopsis: Override On/Off/Toggle PartName
Shortcut: -O 1/0/-1 PartName
Description: Set the current Override status of a rotor or a piston. This can be useful when you want to manually control a joint.

There is three tools allowing to display diferent levels of information on text panels.

• Echo Panel
  
• Log Panel
  
• Debug Panel

The Echo Panel allow to display the exact same information as in the PB terminal.
This can be usefull when you want to get general informations without having to open the terminal.
The default Echo Panel name is: "MArmOS Echo"
To write messages in the Echo Panel, use the MyEcho( Text ); function.

The Log Panel is a log of the last 40 events that has happened.
You can get Loading status, warning messages, argument interpretation and error messages displayed on that screen.
The default Log Panel name is: "MArmOS Log"
To write messages in the Log Panel, use the MyLog( Text ); function.

The Debug Panel is my personnal tool to chase bugs in MArmOS. What it display is always subject to changes.
To write messages in the Debug Panel, use the MyDebug( Text ); function.