Bit control: fixed writes, template reuse and status display

Preparation: control words, bit indices and pages

A Tag is a data point configured in Mingcedar. An integer control word uses individual bits for different on/off states. Bit Index starts at 0. Set writes 1, Reset writes 0, and Toggle reverses the current bit. This tutorial assumes PLC_LINE01.PUMP01.CTRL_WORD and PLC_LINE01.PUMP02.CTRL_WORD are writable WORD (16-bit integer) Tags with good quality and initial value 0. Use bits 3 and 5 only on practice equipment; their real meaning comes from your device signal list.

1. Finish example 1, then duplicate its page for later examples. Examples 2, 3 and 4 are separate target-selection approaches. Keep separate copies instead of combining every Page Script on one page.
2. Insert a rectangle in PowerPoint. Open MX Design → Behaviors → Browse, drag the named behavior from the right-hand catalog onto the component in the left-hand tree, then double-click the behavior to edit it.
3. For a Page Script example, open MX Design → Scripts → Page Script and use the current page's script document. For a Click Script example, use the button's Click Script behavior. Field lists are not JavaScript; do not paste them into a script pane.
4. Complete all steps in each example, save the PPT, and export the full package through MX Design → Export → Export HTML. Open the corresponding page in Mingcedar. Writes require a real interaction on the runtime page.

Expected result The examples use WORD bits 3 and 5, corresponding to values 8 and 32. Expected integer changes assume an initial value of 0 and no concurrent writes from other programs.

• First use: create and publish a screen

Preparation: display both control-word values

Insert text shapes labelled PUMP01 and PUMP02. Add Tag Text, set Target tag as shown and keep other defaults. Retain them in later page copies.

Scroll horizontally to view the full table

Expected result After export, open the page in Mingcedar. Each text shape should show its control word’s current integer value. Confirm that both are 0 before continuing.

Example 1: write a fixed target bit

Add Write Tag Bit to the rectangle, configure the fields below and label it Set. Make two copies with captions and Actions Reset and Toggle. Bit Action below means Bit write → Action; Target Tag is the parent integer name without [3].

Target Tag: PLC_LINE01.PUMP01.CTRL_WORD
Bit Index:  3
Bit Action: Set
Condition:  true

Expected result Click Set, Set, Reset, Toggle, Toggle, waiting for readback after each action. With initial parent value 0, expect 8, 8, 0, 8, 0. Set and Reset can be repeated; Toggle depends on the bit's value before the click.

Example 2: configure two device template instances

Duplicate example 1's page. Change Target Tag on all three buttons to <PLC>.<PUMP>.CTRL_WORD and keep Bit Index 3. <PLC> and <PUMP> are template placeholders filled when configuring an instance; they are not page variables that change during operation.

1. Add a text shape for the device title and group it with the three buttons. Select the whole group, open MX Design → Templates → Library, and click Save selection. Enter Pump bit controls in Template name, confirm PLC and PUMP in Captured variables, and click Save.
2. After confirming the template was saved, remove the original placeholder group from this page. Save selection only saves to the library; it does not remove the original. Hiding it or moving it to another slide in the same PPT still includes it in a full export.
3. Double-click the Pump bit controls card twice. Select each whole instance group, open MX Design → Templates → Edit Instance, enter the Template variables below without quotes, and Save. Export, operate each button group, and inspect the two readback values configured earlier.

// Instance 1: Template variables
PLC  = PLC_LINE01
PUMP = PUMP01

// Instance 2: Template variables
PLC  = PLC_LINE01
PUMP = PUMP02

Expected result Instance 1 operates bit 3 of PLC_LINE01.PUMP01.CTRL_WORD. Instance 2 operates bit 3 of PLC_LINE01.PUMP02.CTRL_WORD. Their appearance and bit index match; their target devices differ.

Example 3: switch the target with a page variable

Save a separate copy of example 1 with its ordinary buttons and put this code in Page Script. selectedControlTag holds a name string. HQVISU_DECLARE_TAGS lists candidate Tags for export dependencies; it creates neither Tags nor permissions.

1. Set Target Tag on all three Write Tag Bit buttons to =selectedControlTag. Keep Bit Index 3. The leading = explicitly evaluates an expression; do not paste this field value into Page Script. The declaration's expression has no leading =.
2. Draw two selector buttons and add Interactions → Set Variable on Click. Set Variable to selectedControlTag on both. Set Value to "PLC_LINE01.PUMP01.CTRL_WORD" and "PLC_LINE01.PUMP02.CTRL_WORD", including string quotes.
3. In the host, select PUMP02 and click Set; then select PUMP01 and click Set. Selection changes a page variable. The bit-write button submits the device operation.

var selectedControlTag = "PLC_LINE01.PUMP01.CTRL_WORD";
HQVISU_DECLARE_TAGS({
  expression: "selectedControlTag",
  read: ["PLC_LINE01.PUMP01.CTRL_WORD", "PLC_LINE01.PUMP02.CTRL_WORD"],
  write: ["PLC_LINE01.PUMP01.CTRL_WORD", "PLC_LINE01.PUMP02.CTRL_WORD"]
});

Expected result The same buttons operate PUMP02 and then PUMP01. Reopening the page restores the initial selection from Page Script.

Example 4A: pass the selected device from an entry page

Copy example 3’s target page and remove device selectors. Set Page Code to pump_bits in MX Design → Page → Nav Path. On a separate entry page, give a button this Click Script to pass pump=PUMP02.

return hqVisuDesigner.openPage("pump_bits", {
  parameters: [{ key: "pump", value: "PUMP02" }]
});

Expected result The target page receives the pump parameter. This does not change <PUMP> in Template Edit. Complete the next step to convert the parameter into a target name.

Example 4B: validate the page parameter and select a target

Replace the entire pump_bits Page Script; do not append after the old initialization. Only the two configured devices are allowed. Missing or unknown parameters leave the target uninitialized, even if the page displays. Keep Target Tag =selectedControlTag and Bit Index 3 on all three buttons.

var pumpCode = GetPageParameter("pump", "");
if (pumpCode !== "PUMP01" && pumpCode !== "PUMP02") {
  throw new Error("Open this page with PUMP01 or PUMP02 selected");
}
var selectedControlTag = "PLC_LINE01." + pumpCode + ".CTRL_WORD";
HQVISU_DECLARE_TAGS({
  expression: "selectedControlTag",
  read: ["PLC_LINE01.PUMP01.CTRL_WORD", "PLC_LINE01.PUMP02.CTRL_WORD"],
  write: ["PLC_LINE01.PUMP01.CTRL_WORD", "PLC_LINE01.PUMP02.CTRL_WORD"]
});

Expected result Duplicate the entry button and change PUMP02 to PUMP01 in its code. Open each target and confirm its write through readback. Then temporarily change one entry parameter to PUMP99 and export again. Its bit-write buttons must not write a device. Restore the valid parameter afterwards.

Example 5A: configure bit and action selectors

Copy example 3 with its Page Script and selectors, then append these two lines. Replace the three Write Tag Bit buttons with an Execute button and Click Script; configure it next. Bit Index cannot take variables, so dynamic indices require the script API.

1. Draw Bit 3 and Bit 5 selector buttons with Set Variable on Click. Set Variable to selectedBitIndex and Value to the numbers 3 and 5 without quotes.
2. Draw Set, Reset and Toggle selector buttons with Set Variable on Click. Set Variable to selectedBitAction and Value to "Set", "Reset" and "Toggle", including quotes.
3. These selectors only change variables. Execute submits one write. Do not also attach Write Tag Bit to the Execute button.

var selectedBitIndex = 3;
var selectedBitAction = "Set";

Expected result The page holds three selections: device target, bit index and action. Changing them has not yet written to the device.

Example 5B: validate and execute the write

Put this code in Execute → Click Script. The example allows two devices, bits 3/5 and Set/Reset/Toggle. Pass variables directly, without = or quoted variable names.

if (["PLC_LINE01.PUMP01.CTRL_WORD", "PLC_LINE01.PUMP02.CTRL_WORD"].indexOf(selectedControlTag) < 0) {
  throw new Error("The device is not in the allowlist");
}
var rawBit = selectedBitIndex;
if ((typeof rawBit !== "number" && typeof rawBit !== "string") || String(rawBit).trim() === "") {
  throw new Error("Select a valid bit index");
}
var bit = Number(rawBit);
if (!Number.isInteger(bit) || [3, 5].indexOf(bit) < 0) {
  throw new Error("This page permits only bits 3 and 5");
}
var action = selectedBitAction;
if (["Set", "Reset", "Toggle"].indexOf(action) < 0) {
  throw new Error("Select Set, Reset or Toggle");
}
return WriteTagBit(selectedControlTag, bit, action);

Expected result Select PUMP02, bit 5 and Set, then Execute. From initial value 0, PUMP02 becomes 32 and PUMP01 remains unchanged. Select Reset and Execute again to return PUMP02 to 0. Bit 4, blank bit indices and unknown actions are rejected before submission.

Example 6A: read bit 3 with a status lamp and text

Copy example 1, keep the write buttons, and add a lamp and text box. State Color and Tag Text show readback; the buttons submit writes.

1. Add Visual States → State Color to the circle. Leave Setup Script empty and use the expression below in Condition. In Action, enable TRUE, FALSE and Fill color. Set TRUE to green #22C55E and FALSE to gray #94A3B8.
2. In State Color's Quality Override, select Follow data quality (border / hide) and set Bad to orange. A fallback false during bad quality is not confirmation that the device is stopped.
3. Add Text → Tag Text to the text box. Set Target tag to PLC_LINE01.PUMP01.CTRL_WORD[3], Fallback value to "--", Prefix to "Bit 3 = " and Suffix to "". This is a read target, so [3] belongs in its name.

ReadTagBoolean("PLC_LINE01.PUMP01.CTRL_WORD[3]", false)

Expected result After Set and device readback, the lamp turns green and the text shows the bit's Boolean value. Reset makes the lamp gray. Even without the write buttons, an external parent-Tag update still changes the display.

Example 6B: let the display follow the dynamic device and bit

Duplicate example 5 and copy in example 6A's lamp and text box. Keep its Page Script and append this read-only declaration. It covers two devices × two bits, for four bit-read names. Write declarations still contain only parent Tags.

1. Change State Color's Condition to ReadTagBoolean(selectedControlTag + "[" + selectedBitIndex + "]", false).
2. Change Tag Text's Target tag to =selectedControlTag + "[" + selectedBitIndex + "]" and Prefix to "Selected bit = ". The leading = belongs only in the target configuration field.
3. In the host, switch PUMP01/PUMP02 and bit 3/5. The selected bit's readback should appear without clicking Execute.

HQVISU_DECLARE_TAGS({
  expression: 'selectedControlTag + "[" + selectedBitIndex + "]"',
  read: [
    "PLC_LINE01.PUMP01.CTRL_WORD[3]", "PLC_LINE01.PUMP01.CTRL_WORD[5]",
    "PLC_LINE01.PUMP02.CTRL_WORD[3]", "PLC_LINE01.PUMP02.CTRL_WORD[5]"
  ]
});

Expected result Display and execution share the selection. Changing it changes what you observe; Execute submits the write.

Example 7A: set on press and reset on release

Save a separate copy of example 1. Add Interactions → Press/Release Script to a new ordinary button. This behavior has no separate Condition. Use a fixed target and bit here so the device cannot change while held. Do not add Click Script or Write Tag Bit to the same button. Put the following code only in Pointer Press.

return WriteTagBit("PLC_LINE01.PUMP01.CTRL_WORD", 3, "Set");

Expected result Press the button with the primary pointer's left button in Mingcedar. Bit 3 receives a Set request. Holding it does not automatically repeat the script.

Example 7B: configure release and understand its limits

Put the following code in Pointer Release of the same Press/Release Script behavior and save. Use Reset for release; Toggle is not a substitute for resetting. Add example 6A's status display and test pressing, releasing, and dragging outside before release.

return WriteTagBit("PLC_LINE01.PUMP01.CTRL_WORD", 3, "Reset");

Expected result Normally bit 3 becomes 1 after press and 0 after release. The runtime also handles matching pointercancel and lostpointercapture release events. Receiving an event is not proof that equipment has reset.

Equipment application limits

• Choose the index for the actual parent integer width: 0–7 for 8-bit, 0–15 for 16-bit, and 0–31 for 32-bit. Bit writing does not currently support 64-bit parent integers.
• WriteTagBit returns the write result; displays use device readback. When several clients or PLC logic update one parent word, do not assume that every protocol guarantees an atomic bit write.
• Template substitution, page variables, page parameters and allowlists have different purposes. Mingcedar still enforces device-write permissions, confirmation and auditing.

• Write Tag Bit fields and API
• Variables, Tags and template parameters
• State Color reference
• Press/Release Script reference