MGC3130 - FengtianGu/Sonoff-Tasmota GitHub Wiki

MGC3130

The MGC3130 is an electrical-field (E-field) based three-dimensional (3D) tracking and gesture controller from Microchip. There are several boards available, which are connected via I2C.

USAGE:

  • uncomment // #define USE_MGC3130 in sonoff/my_user_config.h
  • flash the device before connecting the sensor board
  • wire up SDA and SDL and configure as usual in TASMOTA
  • wire up RESET and TRFR (names may vary on different boards) to free GPIO's and configure them accordingly (TRFR is GPIO: MGC3130_XFER)

EXPECTED BEHAVIOUR:

  • after boot gestures (FLICK, EDGE_FLICK, TOUCH, TAP, DOUBLE_TAP) will be sensed and published via MQTT

Flicks:

Taps:

  • you can select different modes with the COMMANDS, touch will always be sensed and report the duration in 1/20 seconds.

Touch:

  • the airwheel gesture will be sensed and published as "AW" via MQTT with values between 0 and 1023 - clockwise up

Airwheel:

  • after entering postion mode the values for x,y,z will be sensed and published via MQTT with values between 0 and 1023 for x,y. Data is only published, when z is in the upper half (z values are between 0 and 511).

Location sensing in active volume:

  • near the surface you can move your finger without producing location data, i.e. to change the mode.

  • at the moment the circle gestures ((COUNTER)CLOCKWISE) must be activated with the COMMAND: SENSOR91 1 (we must wait 250 ms after the start and can not activate it in the init function, this might differ depending on the board firmware)

COMMANDS:

  • SENSOR36 0 - next mode
  • SENSOR36 1 - gesture mode
  • SENSOR36 2 - airwheel mode
  • SENSOR36 3 - position mode (ATTENTION: this will send a lot of data!)

MQTT-messages:

  • The terminolgy follows the documentation from MICROCHIP, but is shortened to save space especially for RULES. The board is to be viewed like a map, where UP is NORTH and RIGHT is EAST an so on. The big central part of the surface is CENTRE.
  • A movement (FLICK) from LEFT to RIGHT is translated to FLICK-WEST-EAST and then finally shortended to {FL_WE:1}.
  • If you only do a flick at the left edge (with a short movement to the right) this will be EDGE-FLICK-WEST-EAST and then in the final message: {E_FL_WE:1}.
  • A TOUCH (leaving your finger on the board) reports the location and the duration (in counts of 50ms). So touching the centre for a second, publishes messages from {TH_C:1} up to (approx.) {TH_C:20}.
  • Touching for less than 1,25 seconds triggers a TAP-message in the moment of leaving the surface, so on the lower edge we will see: {TP_S:1} (plus some {TH_S:1...x} for the contact duration).
  • Double Tap (like a double click on your mouse) works similiar, but will (at the moment) always trigger a (single) TAP at the same position. Example for the upper edge: {DT_N:1} and before that: {TP_N:1} and some {TH_N:1...x}.
  • Airwheel is a circular finger movement above the sensor, which will trigger a message {AW:0 ... 1023}.
  • In position mode we get {X:0...1023,Y:0...1023,Z:0...511}, where X and Y are 0 in the lower left (west-south) corner. The z value is not published in close proximity to the surface in order to have a chance to switch to another mode with a TOUCH, TAP or DOUBLE-TAP. So the active sensing volume is in the upper z-half of the theoretical maximum sensing volume.

EXAMPLES:

A possible solution to cycle through the modes only with the sensor by double tapping the centre is using RULES:
rule1 on Tele-MGC3130#DT_C do sensor91 0 endon
or with a "long" touch of a second
rule1 on Tele-MGC3130#TH_C > 20 do sensor91 0 endon

CONSIDERATIONS:

This is an extemely versatile sensor and the main problem is not to get it to work somehow in TASMOTA, but to make it usable in a sensible way. We can measure and publish all kinds of data in parallel, but this will likely end up in an unusable situation.
It is important to have a basic understanding of the sensor, to not get confused with seemingly unreasonable messages (DOUBLE TAP triggers a TOUCH (or more than one), then a TAP (after the first lift of the finger) and then a DOUBLE TAP.
The naming conventions of the gestures are according to the data sheets from Microchip, because if we only would have simple FLICKS, it would have made it easy to use: UP, DOWN, LEFT, RIGHT. But we have EDGLE FLICKS and various TOUCHES too, and so the direction name could be ambigous. That's whay we (have to) use NORTH-SOUTH, EAST-WEST ... and NORTH, SOUTH, .... and CENTRE.
To make the MQTT messages not too long, some useful abbreviations have to be found. This ist definitly work in progress.

KNOWN ISSUES:

After the initial flashing the ESP8266/TASMOTA can freeze at startup with a connected sensor board. If this happens disconnect the wires from the MGC3130-board (I2C-wires should be enough), reboot and reconnect.
Keep in mind, that in general many things will interfere with an electrical field. In certain places it can simply be impossible to use such kind of sensor. For testing reasons it is fine to connect the ESP8266-device to the USB-Port of a computer (for POWER and SERIAL), but this will likely lead to weird effects in some cases (i.e. reading of nonsense-location-data by simply touching the keyboard of a connected laptop).
The chip can saturate the I2C-bus and additional I2C-devices can lead to problems. The driver was developed and tested on a SKYWRITER-board from PIMORONI. The behavior of other boards can not be guaranteed.

TO-BE-DONE:

Ideas are welcome and will be integrated if possible.