====== MPINO STUDIO 2 Phase 4-9 · Free-form Box Functions ======

Free-form input places an assignment, expression, or Arduino function call directly in a box function.

{{ :en-us_products:mpino_studio2:free-input-flow.svg?1000 |Free-form input places an assignment, expression, or Arduino function call directly in a box function. }}

This ladder screen uses a free-form box function to call a function from Arduino code.

{{ :en-us_products:mpino_studio2:ladder-free-call-2x.png?1000 |This ladder screen uses a free-form box function to call a function from Arduino code. }}

{{ :en-us_products:mpino_studio2:free-input-examples.svg?1000 |Free-form box-function inputs and example results }}

===== 1. Free-form Input Rules =====

Choose **Free** in the command palette and enter one supported expression. It runs when the left condition is ON; with no contact, it runs every scan.

^ Form ^ Input ^ Meaning ^
| Assignment | ''D0 = (D1 + 10) * 2'' | Store a result in a writable address |
| Function result | ''D0 = readSensor()'' | Store an Arduino function's return value |
| Standalone call | ''doWork()'' | Run a function without storing its return value |

===== 2. Assignments =====

''D0 = D0 + 1'' increments D0 each time it runs. Compound assignments such as ''R0 += 1.5'' are also supported.

^ Operator ^ Meaning ^
| ''='' | Store the right-hand result in the target |
| ''+='' ''-='' ''*='' ''/='' ''%='' | Calculate with the target and store back in it |
| ''&='' ''%%|%%='' ''^='' ''<<='' ''>>='' | Store a bit-operation or shift result back in the target |

===== 3. Arduino Function Calls =====

You can call a function written in Arduino code. If it returns a value, store it in memory as in ''D0 = readSensor()''.

<code cpp>
int readSensor() {
  // Read A0 with the standard Arduino function and return the value.
  return analogRead(A0);
}
</code>

Enter ''D0 = readSensor()'' in the box function. When the left condition is ON, the function runs and stores its return value in D0.

===== 4. Casts =====

Use ''REAL'', ''DW'', ''WD'', ''UD'', or ''UW'' to state the data format used in a calculation. Put the value to convert in parentheses.

^ Command ^ Meaning ^
| ''REAL(D0)'' | Convert to 32-bit float; use to make integer division floating-point |
| ''DW(D0)'' | Convert to signed 32-bit integer |
| ''WD(DD0)'' | Convert to signed 16-bit integer; upper bits may be discarded |
| ''UD(D0)'' | Convert to unsigned 32-bit integer |
| ''UW(DD0)'' | Convert to unsigned 16-bit integer; upper bits may be discarded |

Enter cast names in uppercase and put exactly one value in parentheses. Use a cast in a right-hand expression, not on the left of an assignment.

===== 5. Troubleshooting =====

^ Symptom ^ What to check ^
| The function cannot be found. | Check that it is declared in Arduino code with the same spelling and case. |
| A value increases too quickly. | With no contact it runs every scan. Use a positive-edge contact to run once. |

===== Related Documentation =====

  * [[en-us_products:mpino_studio2:box_functions|Phase 4 · Box Functions]]
  * [[en-us_products:mpino_studio2:box_functions:logic_control|Logic Control Box Functions]]
  * [[en-us_products:mpino_studio2|MPINO STUDIO 2 User Manual]]