MECControl firmware communcation protocol

About the firmware

The MECControl firmware gives you the ability to control devices connected to your Arduino/Genuino Uno or Mega by sending commands to it via the USB port. When connected to a computer, the Arduino/Genuino Uno or Mega behaves like a standard serial port, so there are several ways that you can send commands to it:

The MECControl software itself communicates with your Arduino/Genuino Uno or Mega using these commands.

Note that the MECControl firmware does not allow you to access digital pins 0 and 1 because the Arduino/Genuino Uno or Mega uses these to communicate with the USB port.

Sending commands

Each command should be sent on a single line terminated by a Line Feed. If the MECControl firmware understands your command it will reply with a single line terminated by a Line Feed. The reply will usually be “OK”, unless the command returns a value, or you have used the “Acknowledge Off” command.

Using the Serial Monitor

The Serial Monitor built into the Arduino IDE software is a simple way to send commands to the MECControl firmware. Follow this example to see how it works:

  1. Run the Arduino IDE software.
  2. Plug your Arduino/Genuino Uno or Mega into a USB port.
  3. Click on the Tools menu and look for the Board: Arduino/Genuino Uno or Board: Arduino/Genuino Mega item, depending on which board you have. If it is present, you know your Arduino/Genuino Uno or Mega is successfully connected to your computer.
  4. Click on the Tools menu and select the Serial Monitor item. The Serial Monitor will open in a new window.
  5. In the box at the top of the window, enter the text “Version” and click on the Send button (or press RETURN).
  6. The MECControl firmware should now reply with the text “MECControl Arduino/Genuino m n.n.n” (where m is the model, Uno or Mega, and n.n.n is the firmware version number).

That’s it! You can now try out the other commands!

Command reference

In the following reference, parameters are dark red, with options separated by a bar symbol ( | ) where applicable.

To save on tedious typing, the commands are not case-sensitive and each command also has a shorthand version.

General Commands

Acknowledge

Enables or disables the “OK” reply to most commands sent by the MECControl firmware.

Full command: Acknowledge On|Off

Shorthand: A 1|0

Reply: OK

Break

Interrupts long-running commands such as AnalogWrite, MeccanoidSetServoMotorPosition and StepperMotorStep.

Full command: Break

Shorthand: B

Reply: OK

Version

Replies with the MECControl firmware model and version number.

Full command: Version

Shorthand: V

Reply: MECControl Arduino/Genuino m n.n.n

Arduino Commands

These commands are very similar to the standard Arduino commands that handle pin reading and writing. They can be used to communicate directly with a wide variety of input and output devices.

AnalogPinMode

Sets the mode of the given analogue Pin (0–5).

Pins in Input mode detect voltages between 5V (1023) and 0V (0) with a resolution of about 5mV. Their state can be determined using the AnalogRead command.

Pins in LatchingInput mode detect voltages of 5V (1023) and 0V (0) and remember when their state changes. Their state can be determined using the AnalogRead command. Whenever the AnalogRead command is used, the latch is reset.

Full command: AnalogPinMode Pin Input|LatchingInput

Shorthand: APM Pin I|LI

Reply: OK

AnalogRead

Replies with the Value (0–1023) of the given analogue Pin (0–5).

Full command: AnalogRead Pin

Shorthand: AR Pin

Reply: Value

AnalogWrite

Sets the given digital Pin (2–13) to the given Value (0–255) using Pulse Width Modulation (PWM), ramping up or down smoothly from the previous Value over the given Time (0–65,535 milliseconds).

Full command: AnalogWrite Pin Value Time

Shorthand: AW Pin Value Time

Reply: OK

DigitalPinMode

Sets the mode of the given digital Pin (2–13).

Pins in Input mode or LatchingInput mode detect voltages of 5V (High) and 0V (Low). Their state can be determined using the DigitalRead command.

If left unconnected, pins in Input mode or LatchingInput mode will ‘float’, so their state is unpredicatable. Pins in InputPullup mode or LatchingInputPullup mode are ‘pulled up’ to 5V if left unconnected, so their state will be High.

Pins in LatchingInput mode or LatchingInputPullup mode remember when their state changes. Whenever the DigitalRead command is used, the latch is reset.

Pins in Output mode can supply voltages of 5V (High) and 0V (Low). Their state can be changed using the DigitalWrite and AnalogWrite commands.

Full command: DigitalPinMode Pin Input|InputPullup|LatchingInput|LatchingInputPullup|Output

Shorthand: DPM Pin I|IP|LI|LIP|O

Reply: OK

DigitalRead

Replies with the state (High or Low) of the given digital Pin (2–13).

Full command: DigitalRead Pin

Shorthand: DR Pin

Reply: High|Low

DigitalWrite

Sets the given digital Pin (2–13) to the given state (High or Low).

Full command: DigitalWrite Pin High|Low

Shorthand: DW Pin 1|0

Reply: OK

Meccanoid Commands

These commands can control Meccanoid Servos and Meccanoid LEDs, available from Meccano.

MeccanoidInitialise

Up to four Meccanoid Servos, or up to three Meccanoid Servos and one Meccanoid LED, may be connected in a chain to a single digital Pin.

This command attempts to initialise a chain of Meccanoid devices connected to the given digital Pin (2–13). If it is successful, all LEDs will be turned off and the reply will be “OK”. If the MECControl firmware cannot identify any Meccanoid devices, the reply will be “Timed out”.

When adding Meccanoid devices to an existing chain, always re-initialise them after turning the power off and on again (and pressing the Reset button on your Arduino/Genuino Uno or Mega).

Full command: MeccanoidInitialise Pin

Shorthand: MNI Pin

Reply: OK|Timed out

MeccanoidDisableServoMotor

Disables the Meccanoid Servo motor at the given ChainPosition (0–3) connected to the given digital Pin (2–13). This allows the servo arm to move freely.

Full command: MeccanoidDisableServoMotor Pin ChainPosition

Shorthand: MNDSM Pin ChainPosition

Reply: OK

MeccanoidGetServoMotorPosition

Replies with the Position (18–242) of the Meccanoid Servo motor at the given ChainPosition (0–3) connected to the given digital Pin (2–13).

Full command: MeccanoidGetServoMotorPosition Pin ChainPosition

Shorthand: MNGSMP Pin ChainPosition

Reply: Position

MeccanoidSetServoMotorPosition

Sets the Position (24–232) of the Meccanoid Servo motor at the given ChainPosition (0–3) connected to the given digital Pin (2–13), ramping smoothly from the previous Position over the given Time (0–65,535 milliseconds).

Full command: MeccanoidSetServoMotorPosition Pin ChainPosition Position Time

Shorthand: MNSSMP Pin ChainPosition Position Time

Reply: OK

MeccanoidSetServoLEDColour

Sets the Colour (0–7) of the Meccanoid Servo LED at the given ChainPosition (0–3) connected to the given digital Pin (2–13).

The colours available are Black (0), Red (1), Green (2), Yellow (3), Blue (4), Magenta (5), Cyan (6), and White (7).

Full command: MeccanoidSetServoLEDColour Pin ChainPosition Colour

Shorthand: MNSSLC Pin ChainPosition Colour

Reply: OK

MeccanoidSetLEDColour

Sets the Red, Green and Blue colour mix (all 0–7) of the Meccanoid LED connected to the given digital Pin (2–13), ramping up or down smoothly from the previous colour over the given Time (0–7).

The brightness of each individual colour can range from fully off (0) to fully on (7).

The ramp times available are 0s (0), 0.2s (1), 0.5s (2), 0.8s (3), 1s (4), 2s (5), 3s (6), and 4s (7).

Full command: MeccanoidSetLEDColour Pin Red Green Blue Time

Shorthand: MNSLC Pin Red Green Blue Time

Reply: OK

Stepper Motor Commands

These commands can control unipolar and bipolar stepper motors using a standard two-phase full-step sequence.

StepperMotorDisable

Disables the stepper motor connected to the given digital pins Pin1, Pin2, Pin3 and Pin4 (2–13). This allows the stepper motor shaft to move freely.

The position of the stepper motor will be retained for subsequent commands that use the same Pin1 parameter.

Full command: StepperMotorDisable Pin1 Pin2 Pin3 Pin4

Shorthand: SMD Pin1 Pin2 Pin3 Pin4

Reply: OK

StepperMotorStep

Moves the stepper motor connected to the given digital pins Pin1, Pin2, Pin3 and Pin4 (2–13) the given number of Steps (-32,768–32,767) with the given Interval (1–32,767 milliseconds) between steps.

Using a negative number of Steps will cause the stepper motor to move in the reverse direction.

The position of the stepper motor will be retained for subsequent commands that use the same Pin1 parameter.

Any other commands that are in progress will be blocked until movement is complete, when the reply will be "OK".

Full command: StepperMotorStep Pin1 Pin2 Pin3 Pin4 Steps Interval

Shorthand: SMS Pin1 Pin2 Pin3 Pin4 Steps Interval

Reply: OK