Add motor calibration feature.

[dlech]

Is your feature request related to a problem? Please describe.
Some LEGO Powered Up motors need to have the zero position calibrated. The LEGO MINDSTORMS app can do this, but other apps for other hubs don't have this feature yet.

Describe the solution you'd like
It would be nice if we had a script that we could copy and paste into Pybricks Code to to the calibration.

Describe alternatives you've considered
For people with a MINDSTORMS or SPIKE hub, they can just use the MINDSTORMS app.

Additional context
Related thread: #334 (comment)

[JorgePe]

For people with a MINDSTORMS or SPIKE hub, they can just use the MINDSTORMS app.

Currently, the MINDSTORMS App does not recognize Large Angular Motors (either SPIKE white/blue or Technic grey) as motors that support calibration.

[dlech]

Here is a capture of the calibration procedure from the MINDSTORMS software. The motor is "reset" by stopping UART comms, then it is allowed to come up at 2400 baud rather than doing the initial 115200 baud setting. Then the baud rate is changed to 4800 baud. The the interesting stuff happens at 4800 baud. After the last write at 4800 baud, the hub switches back to 2400 baud but it takes the motor a while to reset again.

The attached data just contains the messages during the 4800 baud portion. I haven't really looked at it yet, so if someone wants to have some fun decoding the write messages, go for it.

Mode 4 is the CALIB mode. According to info reported by the sensor the DATA messages in this mode are supposed to be 2 16-bit integers. After a a certain WRITE command though the DATA changes to a 32-byte payload.

motor-calibration.csv

[dlech]

It looks like it goes something like this:

• This repeats 3 times:

  • Set mode to 4 (CALIB)
  • First iteration only, Write 0x00
  • Write 0x03 + "LEGO-FAC-CAL-"
  • Wait 10 ms
  • Write 0x00
  • Wait 32 ms
  • Write 0x02 0x00 0x40 0x00
  • Wait 7 ms
  • Series of DATA commands
    • On first and third iterations, hub sends NACK and receives DATA 20 times
    • On second iteration, hub sends DATA and receives ACK 5 times
  • Write 0x01
  • Write 0x04
  • Set mode to 0 (POWER) [default mode]
  • Wait about 1 second

• Then:

  • Set mode back to 4 (CALIB)
  • Write 0x03 + "LEGO-FAC-CAL-"
  • Wait 10 ms
  • Write 0x00
  • Wait 32 ms
  • Write 0x02 0x40 0x41 0x00
  • Receive ACK
  • Write 0x01
  • Write 0x04
  • Set mode to 0 (POWER) [default mode]

• Then:

  • Set mode back to 4 (CALIB)
  • Write 0x03 + "LEGO-FAC-CAL-"
  • Wait 10 ms
  • Write 0x00
  • Wait 32 ms
  • Write 0x02 0x48 0x41 0x00
  • Wait 7 ms
  • Hub sends 32-byte DATA and receives ACK 8 times
  • Write 0x01
  • Write 0x04
  • Set mode to 0 (POWER) [default mode]

• Then basically the same as the 1st iteration

  • Set mode back to 4 (CALIB)
  • Write 0x03 + "LEGO-FAC-CAL-"
  • Wait 10 ms
  • Write 0x00
  • Wait 32 ms
  • Write 0x02 0x00 0x40 0x00
  • Hub sends NACK and receives 32-byte DATA 20 times
  • Write 0x01
  • Write 0x04
  • Set mode to 0 (POWER) [default mode]

Finally, stop sending NACKs to allow motor to resync at higher baud rate.

[dlech]

So there appear to be 5 different "commands"

• 0x00: not sure what this does - sent once before 0x03 command and always before 0x02 command
• 0x01: not sure on this either - always sent before 0x04 command
• 0x02: I'm guessing the payload is a 16-bit address - it matches up to the EEPROM address in the STM8S103 processor - the number of bytes read is 640 which matches up to the EEPROM size (last 0x00 is padding since payload has to have size that is a power of 2).
• 0x03: This is probably a "magic" value to unlock programming the flash
• 0x04: Seems to end the programming session

Reading and writing DATA probably reads/writes starting at the address specified in the 0x02 command.

[dlech]

Same CSV with additional columns for DATA messages:

motor-calibration.csv