# Introduction Welcome to Macchina Docs! Here you will find everything there is to know about Macchina products, including instructions for setting things up and several example projects. ![](/files/-LlsA9GqQtQr3ZfVAQj_) {% hint style="success" %} This is an evolving resource that will continue to grow and improve. In an effort to have the best documentation possible, we encourage you to give us feedback or contribute changes directly! If you find any **issues, misinformation, or typos** with any of the articles, click ***Edit on GitHub*** at the top and submit an *Issue*, or submit your proposed changes via *Pull Request*. We appreciate the help! {% endhint %} ## Some especially useful links: Loading your first Arduino Sketch on your M2: {% content-ref url="/pages/-Lhg6858wqkkKL\_WoL9b" %} [Arduino IDE Quick Start](/product-documentation/m2-docs/arduino) {% endcontent-ref %} Adapter board that replaces M2 processor board with PocketBeagle: {% content-ref url="/pages/-LkU\_scyVuYW2srsW6zU" %} [P1 Docs](/product-documentation/p1-docs) {% endcontent-ref %} # Disclaimer Read our user agreement before hacking. {% hint style="danger" %} Your car might be the best hacking canvas you own, but it is also inherently dangerous. Please be familiar with our [user agreement](https://www.macchina.cc/content/disclaimer) and always use best practices when working with cars. Follow the manufacturer's procedure recommendations, don’t operate on a moving vehicle, simulate ideas on a bench, and don’t test on public roads. {% endhint %} # M2 Docs M2 is an open and versatile automotive interface that can take your car to the next level. Use it to customize your ride or as a development platform for your next product. M2 works with almost any vehicle and features an SAM3X ARM Cortex-M3 processor at its core---the same processor as the Arduino Due. An XBee form factor socket allows for many wireless capabilities. ![](/files/-M4PM4VF_53kTcxTFJgT) You can read more about M2 general features [on our website](https://www.macchina.cc/m2-introduction). {% hint style="info" %} To purchase, click here: {% endhint %} ## Goals As we developed the Macchina M2, we set out with the following goals: * Help foster a new generation of car nerds * Develop an innovative product for a wide range of automotive functions * Support the DIY and Open Source ecosystem * Provide companies with a great tool for fast prototyping * Display our ability to develop and mass produce quality hardware ## Specification We designed the M2 to be modular and the result was three main related, but independent, components. The M2 is an open source automotive interface that takes the form of an OBD2 "under-the-Dash" dongle or hard-wired "under-the-hood" device. Each M2 has all the interface circuitry needed to connect to the 5+ standard OBD2 protocols plus other interfaces such as a second CAN bus, LIN bus, and single-wire CAN. It also includes several options for connections to the outside world including: SD card, USB Device and Host, 20-pin (sort of standard) XBee socket, and a general purpose connector. ![](/files/-Lhg6DYJVFrdSeD8R-0C) The **Interface Board** provides most of the hardware support for automotive connections. The goal was for M2 to be able to interface and communicate with as many cars as possible. We crammed 2 channels of CAN, 2 channels of LIN/K-LINE, a J1850 VPW/PWM and even a single-wire CAN (GMLAN) interface onto the board. Automotive environments require the M2 to be seriously strong, so we built in plenty of protection circuitry. Lastly, we have 6 general purpose driver circuits, which can source and sink up to 1 amp of current at 12 volts! The **Processor Board** is the standard computing engine for the Macchina M2. We chose the Arduino Due as the basis of M2's processor board. Shrinking the Due by well over 50% was no small task! We decided to make further improvements by using the High Speed SD card interface and writing the appropriate firmware libraries to allow for faster data logging. We also added several LED options and a couple switches for a more pleasant development experience. Lastly, we tacked on an EEPROM to store variables after power is cut to M2. The processor BCB can be swapped with a [Breakout Board](/product-documentation/m2-docs/detailed-reference/byob) to more easily use the M2 Interface Board with your choice of processor. A **wireless socket** on the M2 Processor Board accommodates a wide variety of wireless options using the popular DIGI XBee form factor socket. Many inexpensive, plug-and-play boards already exist including BLE, WIFI, GSM, 3G, LTE, GPS and others. This can even be used to reprogram the M2 wirelessly. ## History of M2 The Macchina M2 was in development for years prior to its release and the team behind it has been working together on other projects for much longer. Building the M2 has always been a goal of ours. Our [crowdfunding campaign](https://www.kickstarter.com/projects/1029808658/macchina-the-ultimate-tool-for-taking-control-of-y) was the catalyst that transformed us from friends and an idea to a company and a product. We are very thankful to everyone who enabled this transformation. We repay you through our hard work and dedication to this project. We would also like to thank the organizations that have helped build the communities that the M2 relies on: [Arduino](https://www.arduino.cc/), [DIGI International](https://www.digi.com/), [Digi-Key](https://www.digikey.com/), the [EFF](https://www.eff.org/), [Hackaday](http://hackaday.com/), and [Open Garages](http://opengarages.org/). Finally, to the developers who spend their own time building essential tools, answering questions on the forum, and testing, thank you. # Getting Started Unpacking M2 and immediate next steps ## What’s in the Box? Inside your box you should find the following: ![](/files/-Lhg6DPaIfc4v5UaGYfO) * M2 (UTD or UTH) * 26 pin cable harness kit * 24 pin cable harness kit (UTH version only) * Window sticker * Start up card ## Using your M2 There are many ways you can write code and work with M2. One of the quickest and easiest ways is to use the Arduino IDE (Integrated Development Environment) which is what this documentation will use. Many other development environments work well including [Atmel Studio](http://www.microchip.com/development-tools/atmel-studio-7) and [Simulink®](https://www.mathworks.com/products/simulink.html). The first thing you will need to do is [set up the Arduino IDE](/product-documentation/m2-docs/arduino). After that you might choose to build and run an [existing project](http://showcase.macchina.cc/projects.html) or write something your own. There are many [libraries available for the M2](http://showcase.macchina.cc/libraries.html) and most include example sketches that you can run on your M2. ## Enclosures It is ok to do some initial setup before you have an enclosure, but before your M2 spends long periods in the car please consider protecting it. We have a few configurations of enclosures designed and ready for 3D printing. You can download the designs, tweak them as needed, print, share, lather, rinse, repeat. Find more about enclosures [here](/product-documentation/m2-docs/detailed-reference/enclosures). # Arduino IDE Quick Start Begin programming M2 with its first sketch. By completing this guide you will configure the Arduino IDE for developing on the Macchina M2 and run your first sketch on the M2. This will verify both your Arduino IDE setup and your M2 device. The following steps are needed to get started programming on the Macchina M2 with the Arduino IDE: 1. Install the Arduino Desktop IDE 2. Install the Macchina M2 Board Configuration 3. Install drivers 4. Build and upload a sketch ## Arduino Desktop IDE Follow the official installation instructions for your operating system then return here to continue with Macchina M2 specific setup. * [Windows](https://www.arduino.cc/en/Guide/Windows) * [macOS](https://www.arduino.cc/en/Guide/MacOSX) * [Linux](https://www.arduino.cc/en/Guide/Linux) ## Macchina M2 Board Configuration Now that you have the Arduino IDE Installed, you will add support for the for *Macchina M2*. First, you will tell the IDE where to find the Macchina board configuration files. Go to ***File*** > ***Preferences***. Paste ``` https://macchina.cc/package_macchina_index.json ``` into the ***Additional Board Manager URLs:*** box and press ***OK***. This tells the Arduino IDE where to look to find the board configuration files for Macchina boards. Next, you will open the **Boards Manager** to download the needed board configurations. Find the board manager under ***Tools*** > ***Board: "\[...]"*** > ***Boards Manager..***. In the board manager, install **Arduino SAM Boards (32-bit ARM Cortex-M3) by Arduino**. Then install **Macchina SAM Boards (Install Arduino SAM Boards first) by Macchina**. Note: If for any reason you cannot use the Board Manager to install the board configuration files, you have the option to do a [manual install](https://github.com/macchina/arduino-boards-sam/blob/master/CONTRIBUTING.md#local-install-recommended) but will not benefit from the updates notification provided by the Board Manager when new versions are released. {% hint style="warning" %} Having an issue with the Boards Manager? See a common issue and its fix [HERE](broken://pages/-MOleEzJSrszpda8JsBi). {% endhint %} ## Drivers You may need to install a driver to enable your computer to communicate with the Macchina M2 before you can send sketches to it. The Macchina M2 is based on the Arduino Due and uses the same driver. Please visit the official Arduino Due documentation for [instructions on installing drivers](https://www.arduino.cc/en/Guide/ArduinoDue#toc4). Be careful when plugging the micro-USB cable into your M2. The M2's design allows you to put it in a case or enclosure. The connector cable may stick out farther than you expect, because there needs to be clearance space for a case. When you have finished installing drivers, leave your Macchina M2 plugged into the computer. ## Running your first sketch Now that you have the Arduino IDE setup and your M2 connected, you can run your first sketch on the M2 by performing the followings steps in the Arduino IDE. First, you will make **Macchina M2** the active board. ***Tools*** > ***Board: "\[...]"*** > ***Macchina M2***. Next, select the port that your M2 is using. ***Tools*** > ***Port***. Next, open the Blink sketch. ***File*** > ***Examples*** > ***01. Basics*** > ***Blink***. Finally, in the opened window, upload the sketch to your M2 board. ***Sketch*** > ***Upload***. It will take a few moments for the sketch to be written as firmware to your Macchina M2. You can watch the progress at the bottom of the IDE window. When the upload has completed, you should see a flashing LED on your Macchina M2. Congratulations! You have now configured your computer for development on the M2 and run your first program. As a next step, you may choose to learn the names of the other LEDs on the Macchina M2 using the [pin mapping](/product-documentation/m2-docs/detailed-reference/pin-mapping). Then you can practice modifying the sketch to make other LEDs blink. You may also wish to explore the other sketches under the ***Examples*** menu. Most libraries include examples which can be accessed by the ***Examples*** menu after the library is installed. The Macchina M2 Board Configuration you installed includes some libraries which will be listed under the ***Examples for Macchina M2*** section of the ***Examples*** menu. ## Resetting M2 If for some reason your M2 cannot be found by your computer, both in the Arduino IDE and the Device Manager, the M2 can be reset through the following process: 1. Connect the M2 to power. 2. Hold down the ERASE button. 3. While still holding the ERASE button down, press the RESET button. # M2 Code libraries ## **J1850 VPW** {% embed url="" %} J1850 VPW protocol for M2 ## **M2\_12VIO** {% embed url="" %} Provides 6x12V output drivers with over current protection for the output drivers and 6x12V analogue input circuits, plus support for the DUE on chip temperature. ## **M2\_SD\_HSCMI** {% embed url="" %} Gives access to HSMCI (High Speed MultiMedia Card Interface) on M2. ## **OBD9141** {% embed url="" %} A class to read an ISO 9141-2 port found in OBD-II ports. ## **due\_wire** {% embed url="" %} An alternative I2C library for Due with DMA support # CAN bus ## **due\_can** Object oriented canbus library for Arduino Due compatible boards {% embed url="" %} ## **ArduinoDUE\_OBD\_FreeRunningCAN** Free-running CAN and OBDII data acquisition {% embed url="" %} # Single-wire CAN ## **Single-Wire CAN (MCP2515)** {% embed url="" %} Gives M2 single-wire CAN (GMLAN) functionality. Uses external MCP2515 transceiver connected to SAM3X via SPI. Library currently includes an example of sending a SW CAN message. # LIN ## **LIN** {% embed url="" %} # Next Steps with M2 Your M2 can blink its LED, now what? ## SavvyCAN [Visit the dedicated SavvyCAN page.](/projects/m2-projects/use-m2-with-savvycan) Can-Utils If you want to use it with Can-Utils check out our socket-can guide and the Can-Utils GitHub to install this Linux program. OBDII Scanner Sketch If you want to query the ECU, all you need to do is upload this scanner sketch to M2: {% embed url="" %} CanCat Another program you can use is CanCat; it's similar to RfCat. This gives you a powerful python interface to reverse engineer the CAN bus. ## Craig Smith Craig has a number of programs that are based around socketcan and should, in theory, work with the slcan interface possible with M2RET. Examples: ICSim, UDSim, CaringCaribou. I haven’t tested them with an M2 but I think we ought to do so as they provide some useful things we would otherwise lack. I know that CaringCaribou didn’t work well when I tried it with a GVRET device a few years ago but the situation might be different now. # Detailed Reference Pages containing more in depth coverage of M2 # Installation Under-the-dash (UTD) vs. under-the-hood (UTH) and their respective pinouts The Macchina M2 was designed to be modular to give you the option of many installation options. The under-the-dash (UTD) version plugs directly into the OBD2 port of any modern car. The under-the-hood (UTH) version can be spliced into a wire harness. A connector is the only difference between the 2 versions. ![](/files/-Lhg6EisiZsZhh4wrf1P) ## Under-the-Dash (UTD) The "Under-the-Dash" version of the M2 plugs directly into the OBD2 port of the modern car. Any car built after 1996 has an OBD2 port near the steering wheel, under the dash. ![](/files/-Lhg6EiuvBasaMv_7MQI) The OBD2 connector is a 16 pin connector that provides power and a data connection. The image below shows the pin orientation of this 16 pin connector. ![](/files/-Lhg6Eiw_jOWCfIVcUyi) This following table describes the functionality of each pin. | Pin | Schematic name | function | | --- | -------------- | ----------------------- | | 1 | SWC\_BUS | Single Wire CAN | | 2 | J1850+\_BUS | J1850 + BUS | | 3 | MSC\_BUS+ | CAN1 HIGH | | 4 | CHASSIS | CHASSIS GND | | 5 | DGND | Digital GND | | 6 | HSC\_BUS+ | CAN0 HIGH | | 7 | 9141\_K\_BUS | K-LINE or LIN channel 1 | | 8 | TP2\_NET | Test Point | | 9 | TP1\_NET | Test Point | | 10 | J1850-\_BUS | J1850 - BUS | | 11 | MSC\_BUS- | CAN1 LOW | | 12 | TP3\_NET | Test Point | | 13 | TP4\_NET | Test Point | | 14 | HSC\_BUS- | CAN0 LOW | | 15 | 9141\_L\_BUS | L-LINE or LIN channel 2 | | 16 | VIN | +12V INPUT | ## Under-the-Hood (UTH) The "Under-the-Hood" version of the M2 is exactly the same as the "Under-the-Dash" version, but rather than a OBD2 connector, it uses a more general purpose connector. This connector takes the form of a 24-pin pluggable connector. Typical usage for this connector would be a more permanent installation where M2 would be hard-wired or spliced into an existing cable harness. ![](/files/-Lhg6EiyAf5P1nGSKfFO) The image below shows the pin orientation of the 24 pin connector. Notice that the top row has the ODD pins and the bottom row has the EVEN pins. ![](/files/-Lhg6Ej-XbfC9pAZ6xHk) This following table describes the functionality of each pin. | Pin | Schematic name | function | | --- | -------------- | ----------------------- | | 1 | TP1\_NET | Test Point | | 2 | SWC\_BUS | Single Wire CAN | | 3 | J1850-\_BUS | J1850 - BUS | | 4 | J1850+\_BUS | J1850 + BUS | | 5 | DGND | Digital GND | | 6 | DGND | Digital GND | | 7 | MSC\_BUS- | CAN1 LOW | | 8 | MSC\_BUS+ | CAN1 HIGH | | 9 | DGND | Digital GND | | 10 | DGND | Digital GND | | 11 | TP3\_NET | Test Point | | 12 | CHASSIS | CHASSIS GND | | 13 | TP4\_NET | Test Point | | 14 | DGND | Digital GND | | 15 | DGND | Digital GND | | 16 | DGND | Digital GND | | 17 | DGND | Digital GND | | 18 | DGND | Digital GND | | 19 | HSC\_BUS- | CAN0 LOW | | 20 | HSC\_BUS+ | CAN0 HIGH | | 21 | 9141\_L\_BUS | L-LINE or LIN channel 2 | | 22 | 9141\_K\_BUS | K-LINE or LIN channel 1 | | 23 | VIN | +12V INPUT | | 24 | TP2\_NET | Test Point | # Processor Details on the processor board and its components The processor board of M2 contains the brains and the communication circuitry. It features 6 LEDs (5 one-color and 1 RGB LED), 4 switches (2 user switches, RESET and ERASE), an EEPROM, an SD car socket, a Native USB port (that can act as both a USB device or host), and a XBee form factor socket, ![](/files/-Lhg6D-yULOvSHH1MSPO) M2 uses the same processor as the Arduino Due. More information, including original Due schematics found here: Here is the link to the datasheet: # Pin Mapping Use these pin names when programming in the Arduino IDE. **NOTE!** This table is only applicable when using the M2 board as selected from the Tools -> Board menu from the Arduino IDE. See more information [here.](https://github.com/macchina/arduino-boards-sam) **Use the names in the "Mapped Pin Name" column in your Arduino Sketch.** A "pin mapping" describes how the different circuits of your M2 are connected to the processor. For example, the Green LED (DS6 on the schematic) is connected to pin 7 (AKA PA14) of the processor. To make things easier from a programming standpoint, we can map this to a pin name, in this case, the green LED is mapped to the name `DS6` (which is compiled to the value 18). ## LEDs | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ------------ | -------------- | --------------------------- | --------------------------- | | DS2 | DS2 (RED) | LED ON = LOW | PD10 | 32 | 14 | | DS3 | DS3 (YELLOW) | LED ON = LOW | PA5 | 25 | 15 | | DS4 | DS4 (YELLOW) | LED ON = LOW | PD2 | 15 | 16 | | DS5 | DS5 (YELLOW) | LED ON = LOW | PA15 | 8 | 17 | | DS6 | DS6 (GREEN) | LED ON = LOW | PA14 | 7 | 18 | | DS7\_BLUE or RGB\_BLUE | RGB BLUE | LED ON = LOW | PC25 | 136 | 19 | | DS7\_RED or RGB\_RED | RGB RED | LED ON = LOW | PD7 | 20 | 20 | | DS7\_GREEN or RGB\_GREEN | RGB GREEN | LED ON = LOW | PD8 | 21 | 21 | ## Buttons | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | -------------------- | -------------- | --------------------------- | --------------------------- | | Button1 | TACT SW1 | Button pressed = LOW | PC27 | 138 | 22 | | Button2 | TACT SW2 | Button pressed = LOW | PB6 | 121 | 23 | ## SD Card | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ---------------------- | -------------- | --------------------------- | --------------------------- | | SD\_SW | SD\_SW | Card is inserted = LOW | PC30 | 103 | 36 | | MCCK | MCCK | | PA19 | 71 | 37 | | MCCDA | MCCDA | | PA20 | 72 | 38 | | MCDA0 | MCDA0 | | PA21 | 107 | 39 | | MCDA1 | MCDA1 | | PA22 | 81 | 40 | | MCDA2 | MCDA2 | | PA23 | 80 | 41 | | MCDA3 | MCDA3 | | PA24 | 79 | 42 | ## SD Card SPI | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ------------------------ | -------------- | --------------------------- | --------------------------- | | SPI0\_CS1 | SPI0\_nCS1 | Not connected by default | PA29 | 112 | 46 | | SPI0\_MOSI | SPI0 MOSI | Not connected by default | PA26 | 109 | 44 | | SPI0\_CLK | SPI0 CLK | Not connected by default | PA27 | 110 | 45 | | SPI0\_MISO | SPI0 MISO | Not connected by default | PA25 | 108 | 43 | ## 12-volt Outputs | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ----------------------------- | -------------- | --------------------------- | --------------------------- | | GPIO1 | GPIO1 A | SOURCE (J5, Pin 2) | PC3 (PWMH0) | 60 | 24 | | GPIO2 | GPIO2 A | SOURCE (J5, Pin 2) | PC5 (PWMH1) | 63 | 25 | | GPIO3 | GPIO3 A | SOURCE (J5, Pin 2) | PC7 (PWMH2) | 65 | 26 | | GPIO4 | GPIO4 A | SINK (J5, Pin 2) | PC9 (PWMH3) | 67 | 27 | | GPIO5 | GPIO5 A | SINK (J5, Pin 2) | PC20 (PWMH4) | 131 | 28 | | GPIO6 | GPIO6 A | SINK (J5, Pin 2) | PC19 (PWMH5) | 101 | 29 | | GPIO1\_B | GPIO1 B | PWML0 (Beta M2 Hardware only) | PC2 (PWML0) | 59 | 30 | | GPIO2\_B | GPIO2 B | PWML1 (Beta M2 Hardware only) | PC4 (PWML1) | 116 | 31 | | GPIO3\_B | GPIO3 B | PWML2 (Beta M2 Hardware only) | PC6 (PWML2) | 64 | 32 | | GPIO4\_B | GPIO4 B | PWML3 (Beta M2 Hardware only) | PC8 (PWML3) | 66 | 33 | | GPIO5\_B | GPIO5 B | PWML4 (Beta M2 Hardware only) | PC21 (PWML4) | 132 | 34 | | GPIO6\_B | GPIO6 B | PWML5 (Beta M2 Hardware only) | PC22 (PWML5) | 133 | 35 | ## Analog Inputs (0-12V analog input) | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | --------- | -------------- | --------------------------- | --------------------------- | | ANALOG\_1 | ANA 1 | J5 Pin 1 | PB19 | 90 | 86 | | ANALOG\_2 | ANA 2 | J5 Pin 5 | PB18 | 89 | 87 | | ANALOG\_3 | ANA 3 | J5 Pin 9 | PA2 | 85 | 88 | | ANALOG\_4 | ANA 4 | J5 Pin 13 | PA4 | 83 | 89 | | ANALOG\_5 | ANA 5 | J5 Pin 17 | PA3 | 84 | 90 | | ANALOG\_6 | ANA 6 | J5 Pin 21 | PA16 | 78 | 91 | ## GPIO Power Supply Current Sense | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | --------------------------------------------- | -------------- | --------------------------- | --------------------------- | | I\_SENSE\_EN | 12Vio\_EN | GPIO Power Supply Enable | PC24 | 135 | 75 | | I\_SENSE | I SENSE 12V | GPIO Power Supply Analog Current Sense | PB17 | 88 | 93 | | I-SENSE\_INT | OVER\_CURRENT | GPIO Power Supply Interrupt | PD1 | 14 | 76 | | I-SENSE\_DAC | DAC1 | GPIO Power Supply Analog Output to Comparator | PB16 | 77 | 95 | ## CAN | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ----- | -------------- | --------------------------- | --------------------------- | | CANRX0 | CANRX0 | | PA1 | 24 | 69 | | CANTX0 | CANTX0 | | PA0 | 23 | 70 | | CAN0\_CS or HS\_CS | HSC\_S | | PD3 | 16 | 71 | | CANRX1 | CANRX1 | | PB15 | 76 | 72 | | CANTX1 | CANTX1 | | PB14 | 140 | 73 | | CAN1\_CS or MS\_CS | MSC\_S | | PD0 | 13 | 25 | ## Power Supplies | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ----------------------- | -------------- | --------------------------- | --------------------------- | | PS\_BUCK or BUCK\_DIS | BUCK\_nDIS | | PC10 | 117 | 48 | | PS\_J1850\_9141 | J1850 9141 ON | Bring LOW for LOW power | PB5 | 120 | 49 | ## J1850 | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ----- | -------------- | --------------------------- | --------------------------- | | J1850\_PWM\_VPW | J1850\_PWM\_nVPW | | PB8 | 123 | 50 | | J1850\_PWM\_RX | J1850\_PWM\_RX | | PC28 | 139 | 51 | | J1850\_VPW\_RX | J1850\_VPW\_RX | | PC26 | 137 | 52 | | J1850P\_TX | J1850+\_TX | | PC18 | 100 | 53 | | J1850N\_TX | J1850-\_TX | | PC23 | 134 | 54 | ## XBEE | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ---------------- | -------------- | --------------------------- | --------------------------- | | XBEE\_RX or RX0 | XB\_UART RX | UART serial URXD | PA8 | 27 | 0 | | XBEE\_TX or TX0 | XB\_UART TX | UART serial UTXD | PA9 | 2 | 1 | | XBEE\_RST | XB\_nRST | | PC11 | 93 | 4 | | XBEE\_PWM | XB\_RSSI\_PWM | | PB3 | 118 | 7 | | XBEE\_MULT4 | XB\_MULT4 | | PD6 | 19 | 11 | | XBEE\_MULT5 | XB\_MULT5 | | PD9 | 22 | 12 | | XBEE\_MULT1 | XB\_MULT1 | | PC12 | 94 | 8 | | XBEE\_CTS | XB\_nCTS | | PB26 | 1 | 3 | | XBEE\_STAT | XB\_STAT | | PC13 | 95 | 5 | | XBEE\_VREF | XB\_Vref | | PC14 | 96 | 6 | | XBEE\_MULT2 | XB\_MULT2 | | PC15 | 97 | 9 | | XBEE\_RTS | XB\_nRTS | | PB25 | 144 | 2 | | XBEE\_MULT3 | XB\_MULT3 | | PC17 | 99 | 10 | | XBEE\_MULT6 | XB\_MULT6 | | PA7 | 26 | 13 | ![Image showing pin names of the XBEE socket on M2](/files/-Lhg6C7cUTL_woJr2iEU) ## 9141/LIN | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ------- | -------------- | --------------------------- | --------------------------- | | LIN\_KTX | 9141 K TX | Serial1 | PA11 | 4 | 55 | | LIN\_KRX | 9141 K RX | | PA10 | 3 | 56 | | LIN\_KSLP | 9141 K SLP | | PB4 | 119 | 57 | | LIN\_LTX | 9141 L TX | Serial2 | PA13 | 6 | 58 | | LIN\_LRX | 9141 L RX | | PA12 | 5 | 59 | | LIN\_LSLP | 9141 L SLP | | PB7 | 122 | 60 | ## Single-wire CAN | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ----- | -------------- | --------------------------- | --------------------------- | | SWC\_M1 | SWC M1 | | PB0 | 113 | 65 | | SWC\_M0 | SWC M0 | | PB27 | 68 | 64 | | SWC\_SOF | SWC SOF | | PC29 | 102 | 68 | | SWC\_CLK | SWC CLK | | PB22 | 141 | 66 | | SPI0\_CS3 | SPI0\_nCS3 | | PB23 | 142 | 63 | | SWC\_INT | SWC nINT | | PC16 | 98 | 67 | | SWC\_RX0 | SWC nRX0BF | | PB1 | 114 | 61 | | SWC\_RX1 | SWC nRX1BF | | PB2 | 115 | 62 | ## SPI0 | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ------------------------------- | -------------- | --------------------------- | --------------------------- | | SPI0\_MISO | SPI0 MISO | Optionally connected to SD Card | PA25 | 108 | 43 | | SPI0\_MOSI | SPI0 MOSI | Optionally connected to SD Card | PA26 | 109 | 44 | | SPI0\_CLK | SPI0 CLK | Optionally connected to SD Card | PA27 | 110 | 45 | | SPI0\_CS1 | SPI0\_nCS1 | Optionally connected to SD Card | PA29 | 112 | 46 | | SPI0\_CS0 | SPI0\_nCS0 | | PA28 | 111 | 47 | ## 26-Pin GPIO Connector (J5) | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | -------------------- | -------------- | --------------------------- | --------------------------- | | TXD3 | UART3 TX | J5 Pin 7 (3.3V UART) | PD4 | 17 | 77 | | RXD3 | UART3 RX | J5 Pin 8 (3.3V UART) | PD5 | 18 | 78 | | SDA0 | SDA0 | J5 Pin 4 | PA17 | 9 | 79 | | SCL0 | SCL0 | J5 Pin 3 | PA18 | 70 | 80 | | SPI\_CS2 | USART2RX | J5 Pin 15 | PB21 | 92 | 83 | ## Misc. | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ---------------------------- | -------------- | --------------------------- | --------------------------- | | V\_SENSE | AD3 | Analogue input Vehicle Volts | PA6 | 82 | 92 | | CPU\_TEMP or A15 | Internal | CPU Temperature | PD5 | Internal | 94 | ## EEPROM Memory | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ------ | -------------- | --------------------------- | --------------------------- | | SDA1 | SDA1 | Eeprom | PB12 | 86 | 81 | | SCL1 | SCL1 | Eeprom | PB13 | 87 | 82 | ## CPU Test Point | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ------------- | -------------- | --------------------------- | --------------------------- | | USART2TX | USART2TX | TP5 U2TX | PB20 | 91 | 84 | | | unconnected | not connected | PC1 | 55 | 85 | | | UOTGVBOF | | PB10 | 128 | | | | UOTGID | | PB11 | 129 | | | | ERASE\_S | | PC0 | 130 | | | | USART2 CK | | PB24 | 143 | | ## CPU System Pins | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ------------------------- | -------------- | --------------------------- | --------------------------- | | | VDDOUT | | VDDCORE5 | 124 | | | | +3.3V | | VDDIO1 | 11 | | | | +3.3V | | VDDIO2 | 62 | | | | +3.3V | | VDDIO3 | 105 | | | | +3.3V | | VDDIO4 | 125 | | | | DGND | | GND1 | 12 | | | | DGND | | GND2 | 58 | | | | DGND | | GND3 | 106 | | | | DGND | | GND4 | 126 | | | | DGND | | GNDPLL | 33 | | | | DGND | | GNDANA | 74 | | | | VDDPLL | | VDDPLL | 34 | | | | XOUT | Crystal | XOUT | 35 | | | | XIN | Crystal | XIN | 36 | | | | D+ | Micro USB pin3 | DHSDP | 37 | | | | D- | Micro USB pin2 | DHSDM | 38 | | | | VBUS | Micro USB pin1 +5Volts | XUSB | 39 | | | | VBG | | VBG | 40 | | | | VDDUTMI | | VDDUTMI | 41 | | | | DFSDP | | DFSDP | 42 | | | | DFSDM | | DFSDM | 43 | | | | DGND | Grounded pin | GNDUTMI | 44 | | | | VDDOUT | | GNDUTMI | 45 | | | | DGND | Grounded pin | JTAGSEL | 46 | | | | M\_nRST/SWC nRESET | MCP2515 Reset | NRSTB | 47 | | | | XIN32 | N/C | XIN32 | 48 | | | | XOUT32 | N/C | XOUT32 | 49 | | | | | N/C | SHDN | 50 | | | | | Grounded via Resistor | TST | 51 | | | | | +3.3V via Resistor | VDDBU | 52 | | | | | +3.3V via Resistor | FWUP | 53 | | | | | Grounded pin | GNDBU | 54 | | | | VDDOUT | | VDDOUT | 56 | | | | +3.3V | | VDDIN | 57 | | | | TP5 | | NRST | 69 | | | | VDDANA | VoltageAnalogue | VDDANA | 73 | | | | DGND | Ground Analogue | GNDANA | 74 | | | | DGND | Analogue Digital Volt ref | ADVREF | 75 | | | | | | PB9 | 127 | | ## JTAG | Mapped Pin Name (use these in your sketch) | M2 Board Signal Name | Notes | SAM3X Pin Name | Processor CHIP physical PIN | PinDescription Array Number | | ------------------------------------------ | -------------------- | ----- | -------------- | --------------------------- | --------------------------- | | | JTAG-TCK | TP1 | PB28 | 28 | | | | JTAG-TDI | TP2 | PB29 | 29 | | | | JTAG\_TDO | TP3 | PB30 | 30 | | | | JTAG-TMS | TP4 | PB31 | 31 | | # Automotive Interfaces The M2 Inferface Board contains both the power supply circuitry and the automotive interfaces required to communicate with your car. This includes: * 2x CAN bus * 1x SWCAN (Single-Wire CAN) * 2x LIN/9141 * J1850 VPW/PWM To find libraries for any M2 interfaces, try the [Macchina Community Showcase](http://showcase.macchina.cc/libraries.html). ![](/files/-Lhg6CD8Cb9DXtcE91wG) ## 26-pin **general purpose** connector Every M2 has a 26-pin general purpose "expansion" connector that provides even more connection options. For example: UART, SPI, I2C, six general purpose 12V drivers and six 12V analog inputs. See the [schematic](https://github.com/macchina/m2-hardware) for actual pinout details. Part number for this 2mm pitch connector is: [Hirose DF11-26DP-2DS(52)](https://www.digikey.com/product-detail/en/hirose-electric-co-ltd/DF11-26DP-2DS-52/H2876-ND/524308) Refer to the following diagram for pin 1 location. Note that the **ODD** pins are on the **TOP** row and the **EVEN** pins are on the **BOTTOM** row. ![](/files/-Lhg6CDAodvSXcXpROkA) The following table shows what the function for each pin: | Pin | Function | Notes | | --- | ---------------- | ----------------------- | | 1 | IN 1 | 0-12V Analog Input | | 2 | OUT 1 | 12V SOURCE Output | | 3 | SCL0 | 3.3V logic | | 4 | SDA0 | 3.3V logic | | 5 | IN 2 | 0-12V Analog Input | | 6 | OUT 2 | 12V SOURCE Output | | 7 | UART3 TX | 3.3V logic | | 8 | UART3 RX | 3.3V logic | | 9 | IN 3 | 0-12V Analog Input | | 10 | OUT 3 | 12V SOURCE Output | | 11 | SPI0 CLK | 3.3V logic | | 12 | SPI0 MISO | 3.3V logic | | 13 | IN 4 | 0-12V Analog Input | | 14 | OUT 4 | 12V SINK Output | | 15 | SPI0 CS/USART2RX | 3.3V logic | | 16 | SPIO MOSI | 3.3V logic | | 17 | IN 5 | 0-12V Analog Input | | 18 | OUT 5 | 12V SINK Output | | 19 | +12VIO | +12V (switched output) | | 20 | +5V | +5 (constant output) | | 21 | IN 6 | 0-12V Analog Input | | 22 | OUT 6 | 12V SINK Output | | 23 | +3.3V | +3.3V (constant output) | | 24 | +12V | +12V (constant output) | | 25 | GND | Ground | | 26 | GND | Ground | Find more about six 12V source/sink driver circuits [here](/product-documentation/m2-docs/detailed-reference/12vio). ## CAN [Controller Area Network](https://en.wikipedia.org/wiki/CAN_bus) CAN bus is a vehicle bus standard used in most cars built after 2006. It is a message-based protocol that allows modules within a car to communicate with one another. While the physical layer is understood and open, the actual meaning of the messages sent over the bus are not. While some messages are legislated to be "standard", the majority of CAN messages in your typical car are not well documented. The M2 has 2 CAN channels (in addition to the single-wire CAN channel) that can interface directly to the CAN bus network of your car. The M2 uses the 2 built-in CAN controllers found in the SAM3X and 2 external TJA1051 transceivers. Here is a typical example: ![](/files/-Lhg6CDILoDl7_u0_Xo2) Here is the link to the datasheet: CAN bus connections can be found on either the 16-pin OBD2 connector on the under-the-dash M2 or the 24-pin connector used by the under-the-hood M2. ## Single-wire CAN The Macchina M2 provides single-wire CAN support using a MCP2515 CAN controller. ## LIN [Local Interconnect Network](https://en.wikipedia.org/wiki/Local_Interconnect_Network) bus is an inexpensive, single wire, serial network protocol used in many modern cars. Typically, LIN would be used to control and monitor lower-priority devices such as seat positions, door locks, radio and illumination. The M2 has 2 LIN channels that can interface directly to the LIN bus network of your car. Your M2 uses 2 external TJA1027 transceivers connected via UART to the processor. Here is the link to the datasheet: Note that the TJA1027 transceiver is used for both LIN and ISO9141 (K-LINE/L-LINE) for a total of 2 channels. LIN bus connections can be found on either the 16-pin OBD2 connector on the under-the-dash M2 or the 24-pin connector used by the under-the-hood M2. ## K-line (aka ISO9141, KWP2000) ISO9141/K-line is typically found in Chrysler, European, and Asian vehicles built before around 2005. This protocol is similar to RS-232 but at different voltage levels and on a single, bidirectional line. Some cars require a secondary line (sometimes referred to as L-Line). M2 has two K-line channels and uses the TJA1027 transceiver to interface the 12-volt single bidirectional line from the vehicle to a 3.3V UART connection. While this part is designed for LIN, it is also K-line compatible. Here is typical interface circuit showing a channel of ISO9141/LIN connected to the UART channel of the processor. K-line connections can be found on either the 16-pin OBD2 connector on the under-the-dash M2 or the 24-pin connector used by the under-the-hood M2. ![](/files/-Lhg6CDKfpsgw-jI1vSH) Here is the link to the datasheet: ## J1850 M2 supports both J1850 PWM (Pulse-width-modulation) and VPW (Variable Pulse width). **J1850 PWM** is typically found in older Ford vehicles and operates at 41.6 kb/s. The bus is active when `J1850+_BUS` is pulled HIGH to 5V and `J1850-_BUS` is pulled LOW to 0V. **J1850 VPW** is typically found in older GM vehicles and operates at 10.4 kb/s. The voltage range for each protocol is different (0-7V for VPW and 0-5V for PWM). To change between the levels required for PWM and VPW variants of J1850, use this signal: `J1850_PWM_VPW` (M2 board signal name "J1850\_PWM\_nVPW") This signal is connected to physical pin 123 (PB8) of the SAM3X. Make this pin HIGH for PWM and LOW for VPW The following code that will both turn on power to J1850 circuit AND set level for either PWM or VPW: ```cpp void setup() { pinMode(PS_J1850_9141, OUTPUT); pinMode(J1850_PWM_VPW, OUTPUT); digitalWrite(PS_J1850_9141, HIGH); // LOW = no power at +12V_SW/+5V_SW // HIGH = power at +12V_SW/+5V_SW digitalWrite(J1850_PWM_VPW, HIGH); // LOW = ~7.9v (VPW) // HIGH = ~5.9V (PWM) } void loop() { } ``` These signals originate from the vehicle: `J1850+_BUS` connects to pin 2 on the OBD2 port and is used by **BOTH** J1850 PWM and VPW. `J1850-_BUS` connects to pin 10 on the OBD2 port and is used by J1850 PWM These signals connect to the processor as OUTPUTS: `J1850P_TX` (M2 board signal name "J1850+\_TX") is an OUTPUT from the processor used for BOTH J1850 PWM and VPW. "J1850+\_TX" is connected to pin 45 or PC18. This corresponds to the **PWMH6** on peripheral B. * *With J1850\_PWM\_VPW = HIGH (i.e. PWM mode):* When this signal goes HIGH , pin 2 of the OBD2 connector is 5.5V. When this pin is LOW, pin 2 of the OBD2 connector is 0V. * *With J1850\_PWM\_VPW = LOW (i.e. VPW mode):* When this signal goes HIGH , pin 2 of the OBD2 connector is 7.5V. When this pin is LOW, pin 2 of the OBD2 connector is 0V. `J1850N_TX` (M2 board signal name "J1850-\_TX") is an OUTPUT from the processor and is used for J1850 PWM. "J1850-\_TX" is connected to pin 7 or PC23. This corresponds to the **PWML6** on peripheral B. * *With J1850\_PWM\_VPW = HIGH (i.e. PWM mode):* When this signal goes HIGH , pin 10 of the OBD2 connector is 0V. When this pin is LOW, pin 10 of the OBD2 connector is 5V. PWMH6 and PWML6 functionality is described in section 38: Pulse Width Modulation (PWM) of the SAM3X [datasheet](http://www.atmel.com/Images/Atmel-11057-32-bit-Cortex-M3-Microcontroller-SAM3X-SAM3A_Datasheet.pdf). These signals connect to the processor as INPUTS: `J1850_PWM_RX` is an INPUT to the processor. "J1850\_PWM\_RX" is connected to pin 3 or PC28. This corresponds to the **TIOA7** on peripheral B. `J1850_VPW_RX` is an INPUT to the processor. "J1850\_VPW\_RX" is connected to pin 4 or PC26. This corresponds to the **TIOB6** on peripheral B. TIOB6 and TIOA7 functionality is described in section 36: Timer Counter (TC) of the SAM3X [datasheet](http://www.atmel.com/Images/Atmel-11057-32-bit-Cortex-M3-Microcontroller-SAM3X-SAM3A_Datasheet.pdf). # Communication M2 features an XBee socket and micro USB. ## XBee-compatible socket M2 has an *XBee-compatible form factor socket* on the top of the processor board. In other words: two 2mm pitch x 10 pin headers spaced 22mm apart. You an read more about [XBee modules on Wikipedia](https://en.wikipedia.org/wiki/XBee) ![](/files/-Lhg6DP-eGIoLUpnRAeW) There are LOTs of modules that fit this socket, with many different functions. WiFi, BLE, GSM, LTE, Ethernet, etc. When connecting a *XBee-compatible form factor socket* to M2, makes sure that is is oriented so that pin 1 (+3.3V) is at the corner nearest the USB socket as shown here: ![](/files/-Lhg6DP12R4TTBGsP1xv) For an image showing the pin names of the XBee socket on M2, click [here.](/product-documentation/m2-docs/detailed-reference/pin-mapping#xbee) ## USB M2 has a USB connector that can act as either a HOST or DEVICE depending on your code. M2 uses Native USB port only. To print something to the Serial monitor, you'd need to use this command: ```cpp SerialUSB.print("Something"); ``` # M2 Bee-Compatible Add-ons ![](/files/-Lp9HLiw7Ot0dt3XcWs0) Below is a list of Bee-compatible add-ons along with compatibility notes. {% hint style="danger" %} The M2 "Bee-socket" has the "standard" pin 1 voltage of 3.3V. If a module requires a different voltage, alternate power supplies may need to be used. {% endhint %} ### WIFI [Macchina SuperB](https://www.macchina.cc/catalog/m2-accessories/superb) [Macchina SuperBx](https://www.macchina.cc/catalog/m2-accessories/superbx) ### **BLE** [Macchina SuperB](https://www.macchina.cc/catalog/m2-accessories/superb) [Macchina SuperBx](https://www.macchina.cc/catalog/m2-accessories/superbx) ### GSM [NimbeLink SkywireⓇ GPRS Embedded Cellular Modem](https://nimbelink.com/Documentation/Skywire/2G_GPRS/30007_NL-SW-GPRS_Datasheet.pdf) (may need more than 3.3V on Pin 1, so these modems won't work "out-of-the-box".) [Sodaq GPRSbee rev.7](https://shop.sodaq.com/gprsbee-rev7.html) ### **3G** [NimbeLink SkywireⓇ HSPA+ HE910 Embedded Cellular Modem](https://nimbelink.com/Documentation/Skywire/3G_HSPA/30026_NL-SW-HSPA_Datasheet.pdf) (may need more than 3.3V on Pin 1, so these modems won't work "out-of-the-box".) [Digi XBeeⓇ Cellular 3G](https://www.digi.com/products/embedded-systems/cellular-modems/digi-xbee-cellular-3g) [Freematics SIM5360 Cellular Bee Module](https://freematics.com/store/index.php?route=product/product\&product_id=84) (may need more than 3.3V on Pin 1, so these modems won't work "out-of-the-box".) ### **LTE** [NimbeLink SkywireⓇ 4G LTE Cat 3 Embedded Cellular Modem](https://nimbelink.com/Documentation/Skywire/4G_LTE_Cat_3/30012_NL-SW-LTE_Datasheet.pdf) (may need more than 3.3V on Pin 1, so these modems won't work "out-of-the-box".) [Digi XBeeⓇ 3 Cellular LTE-M/NB-IoT](https://www.digi.com/products/embedded-systems/cellular-modems/xbee3-cellular-lte-m-nb-iot) [Digi XBeeⓇ Cellular LTE Cat 1](https://www.digi.com/products/embedded-systems/cellular-modems/digi-xbee-cellular) ### **GPS** [Duinopeak](https://usa.banggood.com/Duinopeak-9600-GPS-Bee-Module-With-GPS-Ceramic-Antenna-Compatible-xBee-Feet-p-1332577.html?gmcCountry=US\¤cy=USD\&createTmp=1\&utm_source=googleshopping\&utm_medium=cpc_bgcs\&utm_content=frank\&utm_campaign=ssc-usg-0802-all-usw\&ad_id=375220358373\&gclid=EAIaIQobChMIi63OnYDW5AIVZBh9Ch1bvwAcEAQYBSABEgL9tfD_BwE\&cur_warehouse=CN)[Ⓡ](https://www.digi.com/products/embedded-systems/cellular-modems/xbee3-cellular-lte-m-nb-iot) [9600 GPS Bee Module with GPS Ceramic Antenna](https://usa.banggood.com/Duinopeak-9600-GPS-Bee-Module-With-GPS-Ceramic-Antenna-Compatible-xBee-Feet-p-1332577.html?gmcCountry=US\¤cy=USD\&createTmp=1\&utm_source=googleshopping\&utm_medium=cpc_bgcs\&utm_content=frank\&utm_campaign=ssc-usg-0802-all-usw\&ad_id=375220358373\&gclid=EAIaIQobChMIi63OnYDW5AIVZBh9Ch1bvwAcEAQYBSABEgL9tfD_BwE\&cur_warehouse=CN) [Seeed GPS Bee kit](http://wiki.seeedstudio.com/GPS_Bee_kit/) ### **NarrowBand-Internet of Things (NB-IoT)** [Dragino NB-IoT Bee](https://www.dragino.com/products/nb-iot/item/132-nb-iot-bee.html)
# Cellular This tutorial will show how to connect your car to the internet using M2, a [Digi XBee Cellular LTE modem](https://www.digi.com/products/xbee-rf-solutions/embedded-cellular-modems/digi-xbee-cellular) and a SIM card. You may also wish to reference the [modem's datasheet](https://www.digi.com/pdf/ds_xbee-cellular.pdf). ## Setup The modem plugs directly into the 20 pin wireless socket on top of your M2. Make sure that it is oriented correctly with the angled chamfers pointed toward the USB/SD side of your M2. Please make sure your M2 is not being powered when plugging in the modem. Before plugging the modem into your M2, make sure to install a SIM card. This modem uses a 4FF (Nano) size SIM card. ![](/files/-Lhg6CcLT0KnjufOPmG6) ## Power As you work with the Digi modem, please keep in mind that it requires more power that your computer can provide directly over a USB port. You have 2 options: * Power your M2 via the OBD2 port (i.e. plugging into your car or some sort of adapter) * Use a powered USB hub. This option is preferable for desktop development. We've had good luck with this inexpensive hub: ## Basic communication A good first step is to check that everything is working it to talk to the modem from your computer, through your M2. For this, you need to program your M2 with a simple sketch that will forward data between the 2 serial ports: * **USBSerial**, the USB connection between the M2 processor and your computer. * **Serial**, the Serial connection between the M2 processor and the XBee socket pins This sketch will also make the GREEN LED blink as the [associate](https://www.digi.com/resources/documentation/digidocs/90001525/default.htm#reference/r_cell_associate_led.htm%3FTocPath%3DHardware|_____4) pin of the modem toggles. The pin signals and locations for the modem can be found [here](https://www.digi.com/resources/documentation/digidocs/90001525/default.htm#reference/r_pinouts_th.htm%3FTocPath%3DHardware%7CPin%20signals%7C_____0). ```cpp int AssociateState = 0; // variable for reading the associate status void setup() { Serial.begin(9600); // Serial port for XBEE socket SerialUSB.begin(9600); // Native USB port pinMode(XBEE_MULT2, INPUT); // DIGI Associate PIN pinMode(DS6, OUTPUT); // Green LED pinMode(XBEE_RST, OUTPUT); digitalWrite(XBEE_RST, HIGH); // Make sure RESET is HIGH pinMode(DS2, OUTPUT); digitalWrite(DS2, LOW); // Turns on Red LED } void loop() { if (SerialUSB.available()) { // read from port 1, send to port 0: int inByte = SerialUSB.read(); Serial.write(inByte); } if (Serial.available()) { // read from port 0, send to port 1: int inByte = Serial.read(); SerialUSB.write(inByte); } AssociateState = digitalRead(XBEE_MULT2); if (AssociateState == HIGH) { digitalWrite(DS6, HIGH); // turn LED on: } else { digitalWrite(DS6, LOW); // turn LED off: } } ``` The second part to a basic communication test is the software on your computer. Digi offers a nice UI called XCTU to communicate with their products. Download the [latest verison](https://www.digi.com/products/xbee-rf-solutions/xctu-software/xctu). Once downloaded and installed, launch XCTU and follow the instructions from [Digi's documentation](https://www.digi.com/resources/documentation/digidocs/90001525/default.htm#tasks/t_add_device.htm%3FTocPath%3DGetting%20started%20with%20the%20XBee%20Cellular%20Modem%20Development%20Kit%7CConfigure%20the%20device%20using%20XCTU%7C_____1). From there, you can do all sorts of fun things, from sending an SMS to connecting to servers to posting data to a website. Several examples are found on [Digi's documentation page](https://www.digi.com/resources/documentation/digidocs/90001525/default.htm). # Power Like all electronics, your M2 requires power to run. Your M2 can be connected directly to a car battery, either from the OBD2 port or some other power wire that provides **5V @ 3 Amps and 3.3V @ 1 amp**. ## Protection M2 employs several circuits to protect the device from overcurrent, reverse voltage, and overvoltage. ## Low power options M2 has several low-power options. One of them is called, **J1850 / ISO 9141 Low Power Control**. We have 2 microcontroller-controlled switches that allow "+12V\_SW" and "+5V\_SW" to be powered on or off depending on conditions. The signal `J1850_9141_ON` controls this and is connected to the SAM3X pin number 120 (PB5) The following code turns on or off the 12V and 5V rails: ```cpp pinMode(PS_J1850_9141, OUTPUT); digitalWrite(PS_J1850_9141, LOW); // LOW = no power at +12V_SW/+5V_SW // HIGH = power at +12V_SW/+5V_SW ``` # Storage/Memory Storage available either via EEPROM or microSD The Macchina M2 offers non-volatile memory or data storage via EEPROM and microSD card. Non-volatile means this data will not be erased when power is cut to M2. ![](/files/-Lhg6EIs27vIKvdOzuVG) ## EEPROM The M2 contains [electrically erasable programmable read-only memory](https://en.wikipedia.org/wiki/EEPROM) (EEPROM) for non-volatile memory. The EEPROM is 32Kbits and controlled via I2C @ address 0x50 Hex. ![](/files/-Lhg6EIuzI195maZTJzw) Here is the link to the datasheet: ## microSD The M2 contains a [microSD](https://en.wikipedia.org/wiki/Secure_Digital) socket. Unlike most Arduino implementations of SD, we chose to employ the HSMCI (High Speed MultiMedia Card Interface) as the connection method. The result being both faster reading and writing, and freeing up the SPI interface for other fun stuff. If for some reason, SPI is needed, we did include some 0 ohm jumpers on the PCB to allow for SPI connection. These are left open by default. ![](/files/-Lhg6EIwwP-1muerlXHA) For in-depth explanation of how the HSMCI works, refer to the [SAM3X datasheet](http://www.atmel.com/Images/Atmel-11057-32-bit-Cortex-M3-Microcontroller-SAM3X-SAM3A_Datasheet.pdf), starting on page 909. Using the SD card slot on your M2 is pretty straight-forward since the complexities are abstracted through a library which was automatically installed for you when you setup your Arduino IDE for the Macchina M2. A description of the examples included with the library can be found [here](https://github.com/macchina/M2_SD_HSMCI#examples). # 12V IO Want to learn more about the 12V IO available? Here are the ins and outs... M2 has several built-in driver circuits that works at your car's 12 volt system. We've designed these circuits to make it easy to connect up both 12 volt inputs AND outputs. This would include things like LEDs, buzzers, sensors, gauges, switches, and solenoids. ## Output The six general purpose 12-volt driver circuits consist of 2 types: **High side and low side.** * Channels 1, 2 and 3 are HIGH side drivers that switch the output to +12V. (aka SOURCE) * Channels 4, 5 and 6 are LOW side drivers that switch the output to GND. (aka SINK) ![](/files/-Lhg6E-0diuBPvSTKmVj) **Note about current limits:** Each channel is capable of sourcing or sinking around 1 amp of current at 12 volts before the protection fuses opens. Of course, this is a MAXIMUM and depends ambient temperature, duty cycle, etc. Also note that drawing the maximum current over all 6 channels at the same time would most likely exceed the limit of your car's OBD2 port fuse. To ensure a better understanding of all of this, we've implemented a current monitoring circuit. When sourcing power, the 12V rail is monitored by an internal current monitor. The goal is to be able to dynamically measure how much power an external device is using AND ensure the total power pulled from the OBD2 port does not exceed X amps and open the car's OBD2 fuse. Here is a cool example of a tachometer gauge connected directly to M2 and displaying actual RPM as read from the CAN bus: ![](/files/-Lhg6E-2QzyCpCXDf3Pm) ## Input M2 has six 12-volt-range input channels. These can either be an analog or digital input. ![](/files/-Lhg6E-45atnZYZOTnmo) ## Library Thankfully, a great library was written to make working with the 12V inputs and outputs much easier, check that out here: # LEDS/Buttons There are several LEDs and Buttons on the processor board of the Macchina M2. These are user programmable and can be used for many applications. ![](/files/-Lhg6DezV6lxIBCKJ7i2) ## LEDs M2 has 5 single-color LEDs and 1 RGB LED. Each LED is active LOW - the processor needs to pull the pin LOW to turn on the LED. ![](/files/-Lhg6Df01hkOGyjRGHZ_) The following table shows what LEDs correspond to what Pin name. | LED | Mapped Pin Name | | ------------ | ----------------------- | | DS2 (RED) | DS2 | | DS3 (YELLOW) | DS3 | | DS4 (YELLOW) | DS4 | | DS5 (YELLOW) | DS5 | | DS6 (GREEN) | DS6 | | RGB RED | DS7\_RED / RGB\_RED | | RGB GREEN | DS7\_GREEN / RGB\_GREEN | | RGB BLUE | DS7\_BLUE / RGB\_BLUE | For example, if you want the Green LED to blink, this sketch will do that for you: ```cpp void setup() { // initialize digital pin DS6 as an output. pinMode(DS6, OUTPUT); } // the loop function runs over and over again forever void loop() { digitalWrite(DS6, LOW); // turn the LED on (LOW is the voltage level) delay(1000); // wait for a second digitalWrite(DS6, HIGH); // turn the LED off by making the voltage HIGH delay(1000); // wait for a second } ``` ## Buttons M2 has 4 buttons on the Processor board. 2 of these buttons (**Button1** and **Button2**) are user-programmable. Use these for triggering something in your program. For example, this code turns on the Red LED when Button 1 is pressed: ```cpp const int buttonPin = Button1; // the number of the pushbutton pin const int ledPin = DS2; // the number of the LED pin int buttonState = 0; // variable for reading the pushbutton status void setup() { pinMode(ledPin, OUTPUT); pinMode(buttonPin, INPUT); } void loop() { buttonState = digitalRead(buttonPin); if (buttonState == LOW) { // If button is pressed digitalWrite(ledPin, LOW); // Turn the Red LED on } else { digitalWrite(ledPin, HIGH); // Turn the Red LED off } } ``` **RESET** button will reset the processor. **ERASE** button is used in conjunction with the RESET button. In the event your program hangs or there is some other issue, power up M2, hold down ERASE and then press and release RESET. This will erase the flash on the processor. # Enclosures Protect your M2! We share all of our 3D models so you can print your own enclosure: [Macchina M2 Enclosures on GitHub](https://github.com/macchina/m2-enclosures) # Breakout Board BYOB - Bring Your Own microcontroller Board The Macchina M2 was designed to be modular to give you the option of using your own microcontroller board in place of our Arduino-based processor board. We've built a [breakout board](https://www.macchina.cc/catalog) to make it easy to connect a Raspberry PI, Edison, Particle, or whatever your favorite microcontroller may be. ![](/files/-Lhg6DASTW1IG6P3VQNA) We've broken out all of the necessary signals to make it easy to hook up. Below is a rendering of the top of the breakout board showing where each signal is found. See the tables below for further description of how pins work. **At a bare minimum, connect +5VOUT and GND to your microcontroller board, supply the interface board with +3.3V at +3.3VIN, and connect up whatever signals you are looking to interface with (CAN, LIN, etc)** ![](/files/-Lhg6DAUGhxytUetcsAl) | PCB Left column label | Interface board signal name | Function | | --------------------- | --------------------------- | --------------------------------------- | | A1 | GPIO1 ANA | Analog input 1 (J5 pin 1) | | A2 | GPIO2 ANA | Analog input 2 (J5 pin 5) | | A3 | GPIO3 ANA | Analog input 3 (J5 pin 9) | | A4 | GPIO4 ANA | Analog input 4 (J5 pin 13) | | A5 | GPIO5 ANA | Analog input 5 (J5 pin 17) | | A6 | GPIO6 ANA | Analog input 6 (J5 pin 21) | | GPIO1A | GPIO1 A | 12V I/O channel 1 (J5 pin 2) | | GPIO2A | GPIO2 A | 12V I/O channel 2 (J5 pin 6) | | GPIO3A | GPIO3 A | 12V I/O channel 3 (J5 pin 10) | | GPIO4A | GPIO4 A | 12V I/O channel 4 (J5 pin 14) | | GPIO5A | GPIO5 A | 12V I/O channel 5 (J5 pin 18) | | GPIO6A | GPIO6 A | 12V I/O channel 6 (J5 pin 22) | | GPIO1-6 B | GPIO1-6 B | Not connected in Release M2 | | ISENSE | I SENSE 12V | | | OC | OVER CURRENT | | | GPIOEN | 12Vio\_EN | | | OCADJ | DAC1 | | | +5VOUT | +5V | +5V OUT (can supply up to \~3A) | | PS\_nDIS | BUCK\_nDIS | | | +3.3VIN | +3.3V | Need to suppply 3.3V to interface board | | +12VOUT | VIN | Vehicle battery voltage | | GND | DGND | Ground | | PCB Right column label | Interface board signal name | Function | | ---------------------- | --------------------------- | --------------------------------- | | CAN0 TX | CANTX0 | CAN channel 0 TX | | CAN0 RX | CANRX0 | CAN channel 0 RX | | CAN1 TX | CANTX1 | CAN channel 1 TX | | CAN1 RX | CANRX1 | CAN channel 1 RX | | CAN0S | HSC\_S | CAN channel 0 Silent mode control | | CAN1S | MSC\_S | CAN channel 1 Silent mode control | | K-TX | 9141 K TX | K-Line or LIN channel 0 TX | | K-RX | 9141 K RX | K-Line or LIN channel 0 RX | | L-TX | 9141 L TX | L-Line or LIN channel 1 TX | | L-RX | 9141 L RX | L-Line or LIN channel 1 RX | | K-SLP | 9141 K SLP | K-Line/LIN0 sleep control input | | L-SLP | 9141 L SLP | L-Line/LIN1 sleep control input | | SWC M1 | SWC M1 | | | SWC M0 | SWC M0 | | | SWC INT | SWC nINT | | | RST | M\_nRST | | | MISO | SPI0 MISO | | | MOSI | SPI0 MOSI | | | nCS3 | SPI0\_nCS3 | | | CLK | SPI0 CLK | | | 1850 P/nV | J1850\_PWM\_nVPW | | | LP | J1850 9141 ON | | | 1850 PRX | J1850\_PWM\_RX | | | 1850 VRX | J1850\_VPW\_RX | | | 1850 +TX | J1850+\_TX | | | 1850 -TX | J1850-\_TX | | | GND | DGND | Ground | | +5VOUT | +5V | +5V OUT (can supply up to \~3A) | # Schematics and Source [The schematics for the M2 boards are open source on GitHub](https://github.com/macchina/m2-hardware) Note: Make sure to refer to the **R3** version if you have a "Release" M2 board. **R2** refers to "Beta" M2 hardware. # Versions of M2 Determine if your M2 processor board is V4 or V3. ![Image showing differences between M2 versions 3 and earlier and version 4](/files/-Lhg6C7irLFKBG9hujZy) There exist multiple versions of M2, the picture above shows several easy to spot differences between V3 and earlier and V4. Most notably are the white buttons and larger arrow indicator on the V4. For the majority of use cases, the version of the M2 will have little effect. # A0 Docs A0 is an exercise in efficient, elegant design. Based on customer demand, we took all of the most sought after automotive interface features--OBD2 connectivity, WiFi, Bluetooth, CAN-only communication and Arduino IDE--and packed them into our smallest footprint yet, creating a deceptively powerful automotive interface at a startlingly attractive price point. ![(beta version, small changes have been made) ](/files/-M4PPzvNXomexiP7Vrtx) {% hint style="info" %} To purchase, click here: {% endhint %} # Quick Start Guide This guide will get you working with two of the most popular applications for A0: Torque and SavvyCAN. ## Use A0 with Torque {% hint style="info" %} The process of connecting A0 with non-Torque apps should be fairly similar to the the one shown below. {% endhint %} #### Connect via Bluetooth Using your phone's Bluetooth settings, connect to ELM327-A0. ![](/files/-MExZc8RbFCx85Yk1c-Y) #### Configure Torque Enter the settings in Torque, and then the "OBD2 Adapter Settings". Ensure connection type is set to Bluetooth and then select ELM327-A0 under the "Choose Bluetooth Device" option. #### ![](/files/-MEx_-pTawh_SuWJ27xS) #### Done! After this point consult the [**Torque Wiki**](https://torque-bhp.com/wiki/Main_Page) to learn how to use Torque. ## Use A0 with SavvyCAN A0RET allows A0 to work with SavvyCAN via Wi-Fi, no wires needed! #### Download SavvyCAN Follow the link below to download the latest release of SavvyCAN as a zip archive. Then unzip to a folder. {% embed url="" %} #### Run SavvyCAN First run vc\_redist.x64.exe to install the Microsoft Visual C++ Redistributable, then run SavvyCAN.exe to open SavvyCAN. ![After opening SavvyCAN for the first time](/files/-MFHLs2avVlw_r6MNcZ_) #### Add a Connection Go to Connection->Open Connection Window to begin adding a new device. ![](/files/-MFHMSjnyCWlBjYiL917) ![](/files/-MFHN3xuIi-5HKXLb_Vm) At this point, plug A0 into the car. Then, from the computer running SavvyCAN, connect to its Wi-Fi network. The defaults are: **SSID:** A0RETSSID **Password:** aBigSecret {% hint style="info" %} The default SSID and Password can be changed through the system menu as described in "Firmware Reference" section. {% endhint %} Click "Add New Device Connection" and select "Network Connection"; the IP address should pre-populate since we have already connected to A0's network. ![](/files/-MFHOJbjPLcxPrDqvGOb) You should now start seeing CAN traffic in the main window of SavvyCAN. The A0-specific steps have now all been completed and you have free reign in the huge playground that is SavvyCAN, visit their extensive documentation below: {% embed url="" %} #### For a more detailed look at A0's built in capabilities, go to: {% content-ref url="/pages/-MZPLbBdFZRRcrbOYi5Y" %} [Firmware Reference](/product-documentation/a0-docs/a0-firmware) {% endcontent-ref %} # Firmware Reference A look at A0's preloaded firmware "ESP32RET" ## Introduction to ESP32RET #### What is ESP32RET? ESP32RET is the name of the firmware that comes pre-loaded on your new Macchina A0. ESP32RET stands for ESP32 (based) Reverse Engineering Tool and provides two primary functionalities\*: ELM327 emulation for use with apps like Torque, and Wi-Fi based connection to SavvyCAN. *\*These functionalities are current as of version 0.1, however future versions may have expanded features.* {% hint style="info" %} *Note: there was a previous version called A0RET that you might still see references to in code, documentation, etc.* {% endhint %} #### ELM327 Emulation, Explained Extra Efficiently Why would you want to emulate an ELM327 device? ELM327 is a closed-source black box interpreter chip (a PIC with some firmware) and you'd much rather know exactly what is being sent to and from your car, right? Another answer is that now you can take advantage of the numerous existing, (semi) working and tested applications out there for every platform. #### SavvyCAN A *Super Powerful* CAN bus reverse engineering and capture tool written by Collin Kidder. Wireless Car Hacking! ## LED Color Codes * RED - Not connected (In WIFIMODE=2 you are creating an AP with the A0, so it will go green immediately because you're the AP) * Green - Ready to connect to application * Blue - Connected to application * Purple - Update mode ## Smartphone apps A0 should be compatible with any ELM327 based app. **Android** - Torque Lite can be found at the link below: {% embed url="" %} Search the Google play store for more options. **iOS** - Software version 14 of iOS breaks support for A0. We are working to regain iOS support. For those interested in testing on 13 or older make sure your app settings are: * Connection = WiFi * IP address = 192.168.4.1 * OBD2 adapter port = 1000 #### Other ELM based software {% embed url="" %} Visit this page for an extensive list of software compatible with ELM327, and by extension ESP32RET. {% endembed %} ## A0 System Menu Many low level configurations can be done via a Serial Terminal (Real-Term, Tera Term, Arduino Serial Monitor, etc). This includes turning ON and OFF WIFI and Bluetooth, setting CAN speed, and setting the WIFI password. Here is the system menu: ``` Short Commands: h = help (displays this message) R = reset to factory defaults s = Start logging to file S = Stop logging to file Config Commands (enter command=newvalue). Current values shown in parenthesis: SYSTYPE=0 - Set board type (0 = Macchina A0, 1 = EVTV ESP32 Board LOGLEVEL=1 - set log level (0=debug, 1=info, 2=warn, 3=error, 4=off) CAN0EN=1 - Enable/Disable CAN0 (0 = Disable, 1 = Enable) CAN0SPEED=500000 - Set speed of CAN0 in baud (125000, 250000, etc) CAN0LISTENONLY=0 - Enable/Disable Listen Only Mode (0 = Dis, 1 = En) CAN0SEND=ID,LEN, - Ex: CAN0SEND=0x200,4,1,2,3,4 MARK= - Set a mark in the log file about what you are about to do. BINSERIAL=0 - Enable/Disable Binary Sending of CANBus Frames to Serial (0=Dis, 1=En) BTMODE=0 - Set mode for Bluetooth (0 = Off, 1 = On) BTNAME=ELM327-A0RET - Set advertised Bluetooth name LAWICEL=1 - Set whether to accept LAWICEL commands (0 = Off, 1 = On) WIFIMODE=2 - Set mode for WiFi (0 = Wifi Off, 1 = Connect to AP, 2 = Create AP SSID=A0RETSSID - Set SSID to either connect to or create WPA2KEY=aBigSecret - Either passphrase or actual key ``` To enter A0 System Menu using the Arduino IDE Serial Monitor, follow these steps: 1. If you don't already have the Arduino IDE installed, download and install the Arduino IDE from [here](https://www.arduino.cc/en/software). 2. Connect A0 to your computer with a USB cable (A0's LED should turn green) 3. Open Arduino IDE. 4. Select the port (port numbers change frequently, your port number will likely be different than the one pictured). ![](/files/-MZTaG48dVwuW_YajSFV) Open an Arduino Serial Monitor: (button in the upper right corner) ![](/files/-MZTcpUNdnQNcIppsWOn) Set your baud rate to 1000000 if it is not already Send a question mark (?) to open the Menu ![](/files/-MZTernFFVnEFpazlt5W) On the left is the current setting. On the right in parentheses are the options. For example, BTmode=0 means Bluetooth is currently off. Send "BTmode=1" in the top line to turn it on. Send another ? to make sure the change was made. ## Re-Flashing ESP32RET ESP32RET is the firmware shipped pre-loaded on A0, follow these steps to return it back to that state. 1. Download the below Zip file 2. Extract the files 3. Plug A0 into your computer via USB 4. Run the correct file for your computer 1. PC - Updater.bat 2. MAC - Updater.sh 3. Linux - Updater.command 5. A green light should appear on the A0 {% file src="/files/-M\_796zlmsoBvJ7kyZEI" %} A0 Firmware Flash File {% endfile %} To compile the code yourself, find everything for ESP32RET here: {% embed url="" %} Feel free to make improvements, submit pull requests and post issues! ## Putting your own code on A0 (using Arduino IDE) {% hint style="danger" %} This removes the preinstalled ESP32RET {% endhint %} #### Using Arduino to install your own sketch The following steps are needed to get started programming on the Macchina A0 with the Arduino IDE: 1. Install the Arduino Desktop IDE 2. Install the Macchina A0 Board Configuration 3. Build and upload a sketch #### Arduino Desktop IDE Follow the official installation instructions for your operating system then return here to continue with Macchina A0 specific setup. * [Windows](https://www.arduino.cc/en/Guide/Windows) * [macOS](https://www.arduino.cc/en/Guide/MacOSX) * [Linux](https://www.arduino.cc/en/Guide/Linux) #### Board Definition {% hint style="warning" %} Before using Arduino IDE with A0 for the first time, you must follow the instructions in the link below to add ESP32 board definitions. {% endhint %} {% embed url="" %} #### Flashing A0 1. Make sure any dependent libraries are in your Arduino>Libraries folder 2. Connect A0 to your computer via a micro USB cable 3. In "Tools" set the Port 4. Select "ESP32 Dev Module" as board type 5. Upload a sketch 6. Press upload Attached is a simple sketch "ColorPallette" for blinking the LED on A0 and the required "FastLED" Library (both need to be unzipped). {% file src="/files/-Ma4esxtmxewFjWrlj\_D" %} ColorPallette Sketch {% endfile %} {% file src="/files/-Ma4fXeLcy2ZMVvuF2sC" %} FastLED Library {% endfile %} # Hardware Reference Pages containing more in depth coverage of A0 ## Installation The Macchina A0 was designed with a convenient under-the-dash form factor that plugs directly into the OBD2 port of any modern car. A0 plugs directly into the OBD2 port of the modern car. Any car built after 1996 has an OBD2 port near the steering wheel, under the dash. Some manufacturers hide the port behind a panel. {% hint style="info" %} Not all cars with OBD2 ports are compatible with A0, only cars with CAN bus on pins 6 and 14 are compatible. Cars from 2008 and newer should be compatible, many older cars are also compatible. Consult wiring diagrams of your car to verify. {% endhint %} ![](/files/-Lhg6EiuvBasaMv_7MQI) ## A0 OBD2 connector pinout The OBD2 connector is a 16 pin connector that provides power and a data connection. The image below shows the pin orientation of this 16 pin connector. ![M2 shown, but same connector as A0](/files/-Lhg6Eiw_jOWCfIVcUyi) This following table describes the functionality of each pin. Please note that A0 only supports a single channel of CAN (CAN0), the rest of the pins are provided for general reference. ### A0 OBD2 pins | Pin | Schematic name | function | | --- | -------------- | -------------- | | 1 | Not connected | - | | 2 | Not connected | - | | 3 | Not connected | - | | 4 | **CHASSIS** | CHASSIS GND | | 5 | **GND** | Digital GND | | 6 | **HSC\_BUS+** | **CAN0 HIGH** | | 7 | Not connected | - | | 8 | Not connected | - | | 9 | Not connected | - | | 10 | Not connected | - | | 11 | Not connected | - | | 12 | Not connected | - | | 13 | Not connected | - | | 14 | **HSC\_BUS-** | **CAN0 LOW** | | 15 | Not connected | - | | 16 | **VIN** | **+12V INPUT** | ## Processor A0 has two PCBs; one contains the ESP32 processor module, while the other contains the OBD2 connector and interface electronics. The upper PCB has a single momentary pushbutton (requires removing the case to access) and a RGB LED clearly visible through the top of the smoked case. A0 can communicate via WiFi and Bluetooth, or using the built-in microUSB port. A0 uses the very popular Espressif ESP32, both as the application processor and the WiFi/BT radio processor. Here is the link to the Espressif ESP32-WROOM32 datasheet: ## Pin Mapping **Use the names in the "Mapped Pin Name" column in your Arduino Sketch.** A "pin mapping" describes how the different circuits of your M2 are connected to the processor. For example, the Green LED (DS6 on the schematic) is connected to pin 7 (AKA PA14) of the processor. To make things easier from a programming standpoint, we can map this to a pin name, in this case, the green LED is mapped to the name `DS6` (which is compiled to the value 18). {% hint style="danger" %} **Coming soon, refer to schematic below for now** {% endhint %} ## CAN bus CAN ([Controller Area Network](https://en.wikipedia.org/wiki/CAN_bus)​) bus is a vehicle bus standard used in most cars built after 2006. It is a message-based protocol that allows modules within a car to communicate with one another. While the physical layer is understood and open, the actual meaning of the messages sent over the bus are not. While some messages are legislated to be "standard", the majority of CAN messages in your typical car are not well documented. The A0 has 1 CAN channel that can interface directly to the CAN bus network of your car. The A0 uses an external TJA1051 CAN transceiver. Here is CAN interface schematic. Note that C19 and C20 are not populated on shipping hardware. ![](/files/-MEdGISs9qllDPOphR3D) Here is the link to the TJA1051 datasheet: ​ CAN bus connections can also be found on the 16-pin OBD2 connector. ## Communication ### WIFI and Bluetooth ESP32 offers both WIFI and Bluetooth as wireless communication. More information here to follow. ### USB A0 has a USB connector that will provide communication to the ESP32 processor AND power to A0. Reflashing ESP32 can be done through the USB port. More information here to follow. ## Power Like all electronics, your A0 requires power to run. Your A0 can be connected directly to an OBD2 port for power. In addition, A0 can be powered via USB. If both USB power and OBD2 power are present, OBD2 power is prioritized. ### Protection A0 employs several circuits to protect the device from overcurrent, reverse voltage, and overvoltage. ## Storage/ Memory A0 uses the ESP32-WROVER-I with following memory size: * 16MB (128Mb) external SPI flash * 8 MB SPI Pseudo static RAM (PSRAM) * A0 can also be custom ordered with additional solder down memory - Email for more information ## LED A0 has an addressable RGB LED for programmable status indication. ## Button A0 has a single momentary pushbutton on the upper PCB, press it to reset the ESP32 {% hint style="info" %} Note the Standard A0 does not ship with access to the button, email us at to order a modified A0 with an exposed button. {% endhint %} ## Schematics The schematics for the A0 boards are open source on GitHub​ here: {% embed url="" %} # Projects ## Macchina Demo Projects {% content-ref url="/pages/-M\_auCnE9dHKucod71oF" %} [Projects](/product-documentation/a0-docs/projects) {% endcontent-ref %} ## Community Projects {% embed url="" %} {% embed url="" %} # Troubleshooting ## SavvyCAN Connection Follow the quick start guide to connect to SavvyCAN. {% hint style="danger" %} This should be done while A0 is powered on but not connected to a vehicle, such as through the USB cable. {% endhint %} Go to Send Frames->Fuzzing, click start fuzzing and then stop fuzzing to send random CAN frames. ![](/files/-MFHPUbnX3MPCU95ktss) Back in the main window, the frames sent by fuzzing should be listed. ![](/files/-MFHPii1RBlb9lsI-1Iz) #### View CAN Traffic in a Vehicle! After this step you're ready to move your A0 to a vehicle and connect to it using the same steps as above (you may want to enable Listen Only to avoid any accidents at first). # SuperB Docs SuperB marries two of hardware’s ubiquitous names - the “Bee” form factor and ESP32. The Bee form factor was derived from DIGI’s XBee industrial grade IoT boards. This form factor has long been used to add wireless connectivity to hardware across the board. But in the maturing market of connected items, two protocols stand as required: Wi-Fi and Bluetooth. ESP32 brings both, and in an easy-to-use package - giving maximum flexibility to your existing hardware and for your next generation of modular, extensible products. ![](/files/-LobK4YiGYFBW06DxvtT) {% hint style="info" %} To purchase, click here: {% endhint %} ## Features * Open source hardware * XBee form-factor compatible (3.3 V levels, UART, SPI and GPIOs broken out to headers) * Based on popular ESP32 SoC * Wi-Fi (802.11 b/g/n) * Bluetooth (Classic and BLE) * Programmable with many tools, including Arduino IDE * OTA (Over-the-Air) flashing capable * Dual Core processor up to 240 MHz * Integrated 4 MB flash - we may upgrade this to 16 MB * Sleep current is less than 5 μA * Fully certified with integrated antenna and software stacks * One programmable LED ## What can SuperB do for you? We designed SuperB as a wireless solution that plugs into the Bee socket of [M2](https://www.macchina.cc/m2-introduction), our automotive interface hardware. Fortunately for you and us, Bee sockets are found everywhere, with over ten million Bee modules deployed to date. Wherever the modular Bee socket is found, SuperB will work. Some examples? [SparkFun’s Wireless Joystick Kit](https://www.sparkfun.com/products/14051) and [Adafruit’s Tweet-a-watt](https://learn.adafruit.com/tweet-a-watt) are two great examples of cool Bee-ready hardware and projects available today. SuperB will come preloaded with [AT Command code](https://github.com/espressif/esp32-at), allowing you to communicate with ESP32 over UART with any microcontroller using standard AT commands. Want to use it like an Arduino? Program SuperB using the [Arduino IDE](https://github.com/espressif/arduino-esp32) for whatever you are looking to build. You can even program SuperB to act as a wireless bootloader for a host system. Better yet, you can reprogram SuperB to wirelessly connect SavvyCan, creating a wireless car hacking dynamic duo with M2! Check back for instructions and code in a future update! ## External Antenna Availability ![Picture depicting SuperB with antenna trace and SuperBx with U.FL connector for external antenna](/files/-Lhg6Cu19HztsduFb1uk) **Built-in 'trace' antenna:** This is the original SuperB design. It uses the ESP32-WROOM-32D module, and the antenna is built into the device. **U.FL for external antenna:** This option uses the ESP32-WROOM-32U module, and allows you to connect your external antenna via U.FL connector. This option works well when you plan to enclose your SuperB in a metal box, tin foil hat or other material that interferes with antenna reception. Please note that users need to provide their own antenna solution for this option. # Getting Started How to flash your SuperB using either a USB adapter board or an M2 ## Overview SuperB can be flashed using an XBee USB adapter board or using M2. As of right now only the USB adapter board supports flashing through the ESP desktop tool; flashing through M2 can only be done through the Arduino IDE. ## Step 1 - Hardware Prep {% tabs %} {% tab title="USB Adapter Board" %} For the instructions that follow, the SuperB is connected to the computer with an XBee USB Adapter board (with one modification), available [here.](https://www.amazon.com/XBee-USB-Adapter-Communication-Connectivity/dp/B017KGBP6Y) ![](/files/-Lhg6E3PzVy8kW-MG1x1) Before the board can be used with the SuperB, VREF and DIO11 need to be bridged on the rear of the board as shown below. ![](/files/-Lhg6E3RWMdTfXfeUCcs) At this point the board can be connected to the computer via USB with the RESET and BOOT buttons controlling EN and IO0, respectively. ![](/files/-Lhg6E3TCJAaPVv7eQ4A) {% endtab %} {% tab title="M2" %} * **1)** Plug SuperB into M2 with the antenna trace/U.FL connector towards the USB port and then plug M2 into computer. (Note the button nomenclature and board orientation) ![](/files/-Lhg6DvMMQ4txs7E0twr) * **2)** Select "Macchina M2" as board type and upload the sketch below: ```cpp int buttonState1 = 0; int buttonState2 = 0; void setup() { pinMode(DS2, OUTPUT); pinMode(DS3, OUTPUT); pinMode(XBEE_RST, OUTPUT); pinMode(XBEE_MULT4, OUTPUT); pinMode(Button1, INPUT); pinMode(Button2, INPUT); SerialUSB.begin(115200); Serial.begin(115200); } char rx_byte = 0; void loop() { if (SerialUSB.available() > 0) { rx_byte = SerialUSB.read(); Serial.write(rx_byte); } if (Serial.available() > 0) { rx_byte = Serial.read(); SerialUSB.write(rx_byte); } buttonState1 = digitalRead(Button1); if (buttonState1 == LOW) { digitalWrite(DS2, LOW); digitalWrite(XBEE_RST, LOW); } else { digitalWrite(DS2, HIGH); digitalWrite(XBEE_RST, HIGH); } buttonState2 = digitalRead(Button2); if (buttonState2 == LOW) { digitalWrite(DS3, LOW); digitalWrite(XBEE_MULT4, LOW); } else { digitalWrite(DS3, HIGH); digitalWrite(XBEE_MULT4, HIGH); } } ``` {% endtab %} {% endtabs %} ## Step 2 - Software {% tabs %} {% tab title="USB Adapter Board + Arduino IDE" %} * **1)** Follow the instructions [here](https://github.com/espressif/arduino-esp32/blob/master/docs/arduino-ide/boards_manager.md) to set up the board manager for ESP32. * **2)** Connect the SuperB with the USB adapter board and select the correct port. * **3)** Place the SuperB into bootloader mode by holding down the BOOT button, pressing and releasing the RESET button, and then releasing the BOOT button. * **4)** Select "ESP32 Dev Module" as board type. * **5)** Upload a sketch. An easy sketch to adapt is the "Blink" sketch found in File>Examples>Basics>Blink. * **6)** Change the three instances of "LED\_BUILTIN" to "26": ```cpp void setup() { // initialize digital pin LED_BUILTIN as an output. pinMode(26, OUTPUT); } // the loop function runs over and over again forever void loop() { digitalWrite(26, HIGH); // turn the LED on (HIGH is the voltage level) delay(1000); // wait for a second digitalWrite(26, LOW); // turn the LED off by making the voltage LOW delay(1000); // wait for a second } ``` * **7)** Upload the sketch and reset the SuperB with the RESET button. {% endtab %} {% tab title="USB Adapter Board + ESP Tool" %} The ESP tool "Flash Download Tools (ESP8266 & ESP32)" can be downloaded [here.](https://www.espressif.com/en/support/download/other-tools)\ The binary files used can be downloaded [here.](https://github.com/macchina/docs/raw/master/superB/flashing/ESP32_AT_Uploader.zip) (Right click>Save link as) * **1)** Open the tool and select "ESP32 DownloadTool". ![Image showing tool selection screen, "ESP32 DownloadTool" is selected](/files/-Lhg6F0CK0NtJBIB9Ve6) * **2)** Enter the binary files and their addresses, and configure the remaining settings as shown below, selecting the corresponding COM port. ![Image showing settings for the ESP tool](/files/-Lhg6F0E0IbEoRD4DqGt) * **3)** Place the SuperB into bootloader mode by holding down the BOOT button, pressing and releasing the RESET button, and then releasing the BOOT button. * **4)** Press start to begin flashing. (\~10sec) * **5)** An easy way to test the SuperB's functionality after flashing is to [send it AT commands](/product-documentation/superb-docs/atcommands). {% endtab %} {% tab title="M2 + Arduino IDE" %} * **1)** Follow the instructions [here](https://github.com/espressif/arduino-esp32/blob/master/docs/arduino-ide/boards_manager.md) to set up the board manager for ESP32. * **2)** Modify the file "platform.txt" found at: **(Windows)** C:\Users\\**YourUsername**\AppData\Local\Arduino15\packages\esp32\hardware\esp32\1.0.2\platform.txt **(MacOS)** /Users/**you**/Library/Arduino15/packages/esp32/hardware/esp32/1.0.3/platform.txt Replace "default\_reset" with "no\_reset" once on line 100 and once on line 101. * **3)** Replace the file "boards.txt" found at: **(Windows)** C:\Users\\***YourUsername***\AppData\Local\Arduino15\packages\esp32\hardware\esp32\1.0.2\boards.txt **(MacOS)** /Users/***you***/Library/Arduino15/packages/esp32/hardware/esp32/1.0.3/boards.txt Replace the existing "boards.txt" file with the one available [here.](https://github.com/kenny-macchina/docs/tree/306ccc81a873f9c8cfe2e05a0cbffb8ff395906b/superB/flashing/boards.txt)\*\*\*\* * **4)** Restart the IDE. * **5)** Open the serial monitor. Place the SuperB into bootloader mode by holding down the BOOT (SW2) button, pressing and releasing the RESET (SW1) button, and then releasing the BOOT (SW2) button. The serial monitor output should look like the one below: ![](/files/-Lhg6DvOTMGMZ2Ca4PKK) * **6)** Select "SuperB on M2" as board type: ![](/files/-Lhg6DvQj9hv3CeNx5Zt) * **7)** A good example sketch can be found in File>Examples>Examples for SuperB on M2>WiFi>WiFiScan. Upload it. * **8)** Close and reopen the serial monitor with "Macchina M2" as the board type. Press RESET (SW1) to begin scanning for access points: ![](/files/-Lhg6DvSLLvcoSptLsLo) {% endtab %} {% endtabs %} # Hardware Schematic of SuperB as well as how to go into bootloader mode ## The SuperB Hardware \ (The SuperB breakout overview, take note of the locations of "EN" and "IO0") ![ESP32 Breakout Overview](/files/-Lhg6E3Lmt6lSQkX5opf) ## Bootloader Mode To place SuperB into bootloader mode, EN must be brought low and returned to high while IO0 is held low. Or, in other words, IO0 must be held low during the EN rising edge. (See depiction below)
![Graph showing EN and IO0](/files/-Lhg6E3Nfp4bKlobVHnh) # Sending AT Commands Test your SuperB by having it scan for nearby access points. * **1)** First, follow the instructions [here](/product-documentation/superb-docs/flashing-superb) to flash SuperB with the ESP tool. * **2)** Follow the instructions [here](https://github.com/espressif/arduino-esp32/blob/master/docs/arduino-ide/boards_manager.md) to set up the board manager for ESP32. * **3)** Connect the SuperB with the USB adapter board and select the correct port. * **4)** Open the serial monitor, with baud equal to 115200 and both NL and CR set. ![](/files/-Lhg6Evbvp-jl2iBHApC) * **5)** Hit RESET on the USB adapter board, the SuperB should report back ready. ![Image showing serial output after a reset](/files/-Lhg6EvdqowA6Ik8G9QA) Try the following two commands sequentially to get a list of access points visible to the SuperB: ``` AT+CWMODE=3 AT+CWLAP ``` ![SuperB scans for access points and prints them to the serial output](/files/-Lhg6Evf-PCZHWeLw3oJ) For a full list of available AT commands click [here.](https://www.espressif.com/sites/default/files/documentation/esp32_at_instruction_set_and_examples_en.pdf) # P1 Docs P1 is a fully featured Linux computer that conveniently plugs into the OBD2 port of your car. Combining the [PocketBeagle](https://beagleboard.org/pocket) single-board computer with an [M2-UTD Interface Board](https://www.macchina.cc/catalog/m2-boards/interface-board-utd) gives you the unprecedented power of running Linux apps directly on P1. ![](/files/-Lls0JO50PJqJTNckBrC) {% hint style="info" %} To purchase, click here: {% endhint %} ## Features * 1GHz ARM® Cortex-A8 running Debian (PocketBeagle by BeagleBoard.org). * Several automotive interfaces, including 2 channels CAN, 1 channel SWCAN * USB A connector - WIFI, BT, Cellular dongles plug in and \*just work\*. * OBD2 connector - just plug 'er in. # Getting Started Setting up P1 and sending/reading CAN messages. This page shows how to set up P1 and interface with your car's OBD port. ![](/files/-LlryQUIN-8kuF3Sb6b1) ## Parts: * [P1](https://www.macchina.cc/catalog/p1-boards/p1-under-dash) (consists of PocketBeagle, Adapter board and Interface board) Note: the Interface board is same as used on M2. The following parts are common and can be found from many sources/manufacturers. * microSD card (included in kit) * WIFI dongle (included in kit) * [USB cable](https://www.macchina.cc/catalog/cables/usb-micro-b-20-cable-5-pin-2824awg-gold-plated-black-15ft) ## Adapter board: The adapter board plugs directly into the M2 Interface board and provides: 1\. Routing of power and signals from M2 Interface board to PocketBeagle. 2\. Battery connector for standard 2-Pin JST battery connector and single cell lithium battery. (Optional) 3\. USB A host port with ESD protection. 4\. Voltage scaling for 6 Analog inputs. 5\. Several 0 ohm jumpers to route signals as needed. Adapter PCB files are found at these links: * [Schematic](https://github.com/macchina/p1-hardware/blob/master/SCH-01010%20R1%20SCHEM.PDF) * [Part location file](https://github.com/macchina/p1-hardware/blob/master/PCB-01010%20R1%20COMPONENT%20LOCATOR%20CLOSE%20UP.PDF) * [Pin number file](https://github.com/macchina/p1-hardware/blob/master/PCB-01010%20R1%20PIN%20NUMBER%20CHART.PDF) ## P1 Setup: ### Step 1: Hook stuff up. The adapter PCB is pre-installed onto the M2 interface board. The PocketBeagle is also pre-installed onto the adapter board. Since the PocketBeagle is not keyed, if you remove, be sure to plug it in so that the USB ports are on the same side. {% hint style="warning" %} A USB wireless adapter can be plugged directly into the board, no powered USB hub required. {% endhint %} ![](/files/-Lls0JO50PJqJTNckBrC) ### Step 2: Create a bootable SD card Follow instructions [**here**](https://beagleboard.org/getting-started) to create a bootable SD card. Once you have a bootable SD card, plug it into the PocketBeagle. Latest images are found [**here**](https://beagleboard.org/latest-images)**.** {% hint style="success" %} Note: The P1 kit ships with pre-installed image on SD card! {% endhint %} Plug a microUSB cable into the PocketBeagle and your computer. After a minute or so, use your favorite terminal to ssh to beagle.local or 192.168.7.2: Login: *debian* Password: *temppwd* [NOTE: if 192.168.7.2 does not work then try 192.168.6.2](https://beagleboard.org/getting-started#step2) ### Step 2.5: Change your password (optional but recommended) We want to make sure that others wont be able to access your device to do this the main thing we are going to do is change the root password. ``` sudo passwd root ``` ### Step 3: Connect to internet. First thing we'll want to do is connect to the internet to be able to download the latest packages. To do that, we'll use WIFI. Type the commands as shown below ``` sudo connmanctl connmanctl> disable wifi Disabled wifi connmanctl> enable wifi Enabled wifi connmanctl> scan wifi Scan completed for wifi connmanctl> services ``` All of the hotspots that your setup can see will be listed here, and look something like this: wifi\_xxxxxx\_xxxxxx\_managed\_psk Run these commands to connect: ``` connmanctl> agent on connmanctl> connect wifi_xxxxxx_xxxxxx_managed_psk Passphrase? xxxxxxxxxxx connected wifi_xxxxxx_xxxxxx_managed_psk connmanctl> quit ``` You should now be connected to your local WiFi. You can check that you have an IP address by typing the following in the terminal window: ``` ifconfig ``` You should now see an IP address under wlan0 and you can now connect to this IP address in the future to program your PocketBeagle. If you have trouble with the WiFi connection after initial setup, then [ssh over the USB cable to the BeagleBone](https://beagleboard.org/static/beaglebone/latest/README.htm#step2) and run: ``` sudo connmanctl disable wifi sudo connmanctl enable wifi iwconfig wlan0 ifconfig wlan0 ``` ### Step 4: Update After connecting to internet, we can update the PocketBeagle by running these two commands, this should take a few minutes. ``` sudo apt update sudo apt upgrade ``` ### Step 5: Set up pins Next we make sure the pins on the PocketBeagle are set up correctly as shown at this link: The following steps only need to be performed once. The correct pin configuration will then persist across reboots. Verify that that these files exist: ``` ls -lt /lib/firmware/PB-CAN0-00A0.dtbo ls -la /lib/firmware/PB-CAN1-00A0.dtbo ``` Edit the boot configuration so the CAN0 and CAN1 pins will be configured automatically: ``` sudo nano /boot/uEnv.txt ``` replace these lines: ``` #uboot_overlay_addr4=/lib/firmware/.dtbo #uboot_overlay_addr5=/lib/firmware/.dtbo ``` with these lines: ``` uboot_overlay_addr4=/lib/firmware/PB-CAN0-00A0.dtbo uboot_overlay_addr5=/lib/firmware/PB-CAN1-00A0.dtbo ``` save the file (ctrl-o) and exit (ctrl-x) and then reboot: ``` sudo reboot ``` Next, we set up the CAN interface and turn it on. Note that we are setting rate at 250Kb/s here. Your car might be a different BAUD rate. {% hint style="success" %} P1 is now set up! Step 6 and beyond are for testing and becoming more familiar with CAN on P1, try them if you'd like, or check out the P1 Mini-Projects. {% endhint %} ### Step 6: print out CAN messages ``` sudo ip link set can0 type can bitrate 250000 listen-only on sudo ifconfig can0 up ``` To see actual data, we need to do 2 things: 1. Plug M2/PocketBeagle into your car or an emulator (No need for hub, and WIFI dongle anymore - those can be unplugged) and 2. enter this command to print output to terminal screen: ``` candump -cae can0,0:0,#FFFFFFFF ``` If everything is set up correctly, you should see something like this: ![](/files/-Lhg6DFbuA5ZmQRDqlD2) While this looks pretty cool, it is hard to see what is going on. Press CTRL+C to end output to terminal. Logging CAN data to a file makes it easier to analyze the data. To do that, use this command to log data to current working directory: ``` candump -l any,0:0,#FFFFFFFF ``` **Optional:** Run these commands to enable the CAN1 interface and print anything received to the terminal: ``` sudo ip link set can1 type can bitrate 250000 listen-only on sudo ifconfig can1 up candump -cae can1,0:0,#FFFFFFFF ``` ### Step 7: Sending CAN messages This should be used for testing purposes only and caution should be taken before sending messages to a real car. Here are instructions on how to send CAN messages on the CAN0 interface. ``` sudo ip link set can0 type can bitrate 250000 sudo ip link set up can0 cansend can0 01a#11223344AABBCCDD ``` ### Step 8: Going further. You can test sending and receiving CAN a couple ways: * [***Loopback test using a single P1.***](/projects/p1-projects/loopback-testing) * Use two sets of P1 and the OBD3way and 12V power supply. * [***A real car!***](/projects/p1-projects/p1-can-vehicle-data) (More to follow) # Pin Mapping This page will describe how the names of the pins on the PocketBeagle/OSD3358 coorespond to signals on the rest of P1. P1 consists of 3 PCBs all stacked together through headers. Each board has its own schematic and each header and signal may have different names on each board. ![UTH and UTD versions of P1](/files/-MdOKjbKwME1yb3dpbEb) {% hint style="danger" %} Caution: Neither PocketBeagle nor Interface board is keyed, so it is possible to plug together incorrectly. Use the above diagram to ensure you are plugging together correctly. Caution: In the case of UTH version - with enough force, it is possible to plug a 24 pin connector into the 26 pin connector socket. Please don't do that. {% endhint %} ## P1 boards: **PocketBeagle** (schematic [here](https://github.com/beagleboard/pocketbeagle/blob/master/PocketBeagle_sch.pdf)). This is the brains of the operation. **Adapter board** (schematic [here](https://github.com/macchina/p1-hardware/blob/master/SCH-01010%20R1%20SCHEM.PDF)). This board acts connects PocketBeagle to the M2 interface board, adds a battery connector and full-sized USB A connector. **Interface board** (schematic [here](https://github.com/macchina/m2-hardware/blob/master/M2/Interface%20Board/Interface%20Board%20Schematic.pdf)). This is the same interface board used with M2. This board has all of the automotive interfaces and power supply. ## P1 headers: Headers connect throughout P1 as follows: | PocketBeagle Headers | Adapter board headers | Interface board headers | | ---------------------- | ---------------------- | ---------------------------- | | **P1** connects to: | **J5** | - | | **P2** connects to: | **J6** | - | | - | **J2** connects to: | J3 | | - | **J3** connects to: | J4 | | - | - | **J5** (26 pin connector) | | - | - | **J1** (UTD) or **J2** (UTH) | ## Mappings: ### 12-volt Outputs | Mapped Pin Name | Function | Notes | PocketBeagle Pin Name | | --------------- | -------- | ---------------------------- | --------------------- | | OUT 1 | SRC | J5 Pin 2 (26 pin connector) | P1\_36 | | OUT 2 | SRC | J5 Pin 6 (26 pin connector) | P2\_3 | | OUT 3 | SRC | J5 Pin 10 (26 pin connector) | P2\_2 | | OUT 4 | SINK | J5 Pin 14 (26 pin connector) | P2\_4 | | OUT 5 | SINK | J5 Pin 18 (26 pin connector) | P1\_33 | | OUT 6 | SINK | J5 Pin 22 (26 pin connector) | P2\_10 | ### Analog Inputs (0-12V analog input) | Mapped Pin Name | Notes | PocketBeagle Pin Name | | --------------- | ---------------------------- | --------------------- | | IN 1 | J5 Pin 1 (26 pin connector) | P1\_19 | | IN 2 | J5 Pin 5 (26 pin connector) | P1\_21 | | IN 3 | J5 Pin 9 (26 pin connector) | P1\_23 | | IN 4 | J5 Pin 13 (26 pin connector) | P1\_25 | | IN 5 | J5 Pin 17 (26 pin connector) | P1\_27 | | IN 6 | J5 Pin 21 (26 pin connector) | P2\_36 | ### GPIO Power Supply Current Sense | Mapped Pin Name | Notes | PocketBeagle Pin Name | | --------------- | --------------------------------------------- | --------------------- | | 12Vio\_EN | GPIO Power Supply Enable | P1\_31 | | SENSE 12V | GPIO Power Supply Analog Current Sense | | | OVER\_CURRENT | GPIO Power Supply Interrupt | | | DAC1 | GPIO Power Supply Analog Output to Comparator | | ### CAN | Mapped Pin Name | Notes | PocketBeagle Pin Name | | ------------------ | ------ | --------------------- | | CANRX0 | CANRX0 | 1\_28 | | CANTX0 | CANTX0 | 1\_26 | | CAN0\_CS or HS\_CS | HSC\_S | 1\_20 | | CANRX1 | CANRX1 | 2\_09 | | CANTX1 | CANTX1 | 2\_11 | | CAN1\_CS or MS\_CS | MSC\_S | 2\_30 | ### Power Supplies | Mapped Pin Name | Notes | PocketBeagle Pin Name | | --------------------- | ----------------------- | --------------------- | | PS\_BUCK or BUCK\_DIS | | | | PS\_J1850\_9141 | Bring LOW for LOW power | P2\_19 | ### J1850 | Mapped Pin Name | Notes | PocketBeagle Pin Name | | --------------- | ----- | --------------------- | | J1850\_PWM\_VPW | | | | J1850\_PWM\_RX | | | | J1850\_VPW\_RX | | | | J1850P\_TX | | | | J1850N\_TX | | | ### 9141/LIN | Mapped Pin Name | Pin name | Notes | PocketBeagle Pin Name | | --------------- | ---------- | ---------- | --------------------- | | LIN\_KTX | 9141 K TX | LIN1 TX | P2\_7 | | LIN\_KRX | 9141 K RX | LIN1 RX | P2\_5 | | LIN\_KSLP | 9141 K SLP | LIN1 Sleep | P2\_22 | | LIN\_LTX | 9141 L TX | LIN2 TX | P1\_30 | | LIN\_LRX | 9141 L RX | LIN2 RX | P1\_32 | | LIN\_LSLP | 9141 L SLP | LIN2 Sleep | P2\_28 | ### Single-wire CAN | Mapped Pin Name | Pin Name | Notes | PocketBeagle Pin Name | | --------------- | ---------- | ----- | --------------------- | | SWC\_M1 | SWC M1 | | | | SWC\_M0 | SWC M0 | | | | SWC\_SOF | SWC SOF | | | | SWC\_CLK | SWC CLK | | | | SPI0\_CS3 | SPI0\_nCS3 | | | | SWC\_INT | SWC nINT | | | | SWC\_RX0 | SWC nRX0BF | | | | SWC\_RX1 | SWC nRX1BF | | | # Interfaces The Interface Board for P1 is exactly the same as M2. It contains both the power supply circuitry and the automotive interfaces required to communicate with your car. This includes: * 2x CAN bus * 1x SWCAN (Single-Wire CAN) * 2x LIN/9141 * J1850 VPW/PWM ![](/files/-Lhg6CD8Cb9DXtcE91wG) ## 26-pin **general purpose** connector Every P1 has a 26-pin general purpose "expansion" connector that provides even more connection options. For example: UART, SPI, I2C, six general purpose 12V drivers and six 12V analog inputs. See the [schematic](https://github.com/macchina/P1-hardware) for actual pinout details. Part number for this 2mm pitch connector is: [Hirose DF11-26DP-2DS(52)](https://www.digikey.com/product-detail/en/hirose-electric-co-ltd/DF11-26DP-2DS-52/H2876-ND/524308) Refer to the following diagram for pin 1 location. Note that the **ODD** pins are on the **TOP** row and the **EVEN** pins are on the **BOTTOM** row. ![](/files/-Lhg6CDAodvSXcXpROkA) The following table shows what the function for each pin: | Pin | Function | Notes | | --- | ---------------- | ----------------------- | | 1 | IN 1 | 0-12V Analog Input | | 2 | OUT 1 | 12V SOURCE Output | | 3 | SCL0 | 3.3V logic | | 4 | SDA0 | 3.3V logic | | 5 | IN 2 | 0-12V Analog Input | | 6 | OUT 2 | 12V SOURCE Output | | 7 | UART3 TX | 3.3V logic | | 8 | UART3 RX | 3.3V logic | | 9 | IN 3 | 0-12V Analog Input | | 10 | OUT 3 | 12V SOURCE Output | | 11 | SPI0 CLK | 3.3V logic | | 12 | SPI0 MISO | 3.3V logic | | 13 | IN 4 | 0-12V Analog Input | | 14 | OUT 4 | 12V SINK Output | | 15 | SPI0 CS/USART2RX | 3.3V logic | | 16 | SPIO MOSI | 3.3V logic | | 17 | IN 5 | 0-12V Analog Input | | 18 | OUT 5 | 12V SINK Output | | 19 | +12VIO | +12V (switched output) | | 20 | +5V | +5 (constant output) | | 21 | IN 6 | 0-12V Analog Input | | 22 | OUT 6 | 12V SINK Output | | 23 | +3.3V | +3.3V (constant output) | | 24 | +12V | +12V (constant output) | | 25 | GND | Ground | | 26 | GND | Ground | ## CAN [Controller Area Network](https://en.wikipedia.org/wiki/CAN_bus) CAN bus is a vehicle bus standard used in most cars built after 2006. It is a message-based protocol that allows modules within a car to communicate with one another. While the physical layer is understood and open, the actual meaning of the messages sent over the bus are not. While some messages are legislated to be "standard", the majority of CAN messages in your typical car are not well documented. The P1 has 2 CAN channels (in addition to the single-wire CAN channel) that can interface directly to the CAN bus network of your car. The P1 uses the 2 built-in CAN controllers found in the SAM3X and 2 external TJA1051 transceivers. Here is a typical example: ![](/files/-Lhg6CDILoDl7_u0_Xo2) Here is the link to the datasheet: CAN bus connections can be found on either the 16-pin OBD2 connector on the under-the-dash P1 or the 24-pin connector used by the under-the-hood P1. ## Single-wire CAN The Macchina P1 provides single-wire CAN support using a MCP2515 CAN controller. ## LIN [Local Interconnect Network](https://en.wikipedia.org/wiki/Local_Interconnect_Network) bus is an inexpensive, single wire, serial network protocol used in many modern cars. Typically, LIN would be used to control and monitor lower-priority devices such as seat positions, door locks, radio and illumination. The P1 has 2 LIN channels that can interface directly to the LIN bus network of your car. Your P1 uses 2 external TJA1027 transceivers connected via UART to the processor. Here is the link to the datasheet: Note that the TJA1027 transceiver is used for both LIN and ISO9141 (K-LINE/L-LINE) for a total of 2 channels. LIN bus connections can be found on either the 16-pin OBD2 connector on the under-the-dash P1 or the 24-pin connector used by the under-the-hood P1. Use following Commands to init the LIN-Bus: ``` config-pin P2_22 hi # Enable LIN-Bus1 config-pin P2_28 hi # Enable LIN-Bus2 config-pin P2_19 hi # Enable Power for LIN ``` Use following Commands to see if the Lin-Busses are working: ``` cat /tty/ttyS4 # Lin1 cat /tty/ttyS0 # Lin2 ``` Attention: To use the LIN2 Bus, you will need to solder bridges on the R06 and R07 which are not soldered on the Board. Refer here for Instructions: [https://github.com/macchina/p1-hardware/blob/master/PCB-01010 R1 COMPONENT LOCATOR CLOSE UP.PDF](https://github.com/macchina/p1-hardware/blob/master/PCB-01010%20R1%20COMPONENT%20LOCATOR%20CLOSE%20UP.PDF) {% tabs %} {% tab title="Plain Text" %} ``` Add in boot/uEnv.txt the console option to redirect output to ttyS2: console=ttyO2,115200n8 ``` {% endtab %} {% endtabs %} ## K-line (aka ISO9141, KWP2000) ISO9141/K-line is typically found in Chrysler, European, and Asian vehicles built before around 2005. This protocol is similar to RS-232 but at different voltage levels and on a single, bidirectional line. Some cars require a secondary line (sometimes referred to as L-Line). P1 has two K-line channels and uses the TJA1027 transceiver to interface the 12-volt single bidirectional line from the vehicle to a 3.3V UART connection. While this part is designed for LIN, it is also K-line compatible. Here is typical interface circuit showing a channel of ISO9141/LIN connected to the UART channel of the processor. K-line connections can be found on either the 16-pin OBD2 connector on the under-the-dash P1 or the 24-pin connector used by the under-the-hood P1. ![](/files/-Lhg6CDKfpsgw-jI1vSH) Here is the link to the datasheet: ## J1850 P1 supports both J1850 PWM (Pulse-width-modulation) and VPW (Variable Pulse width). {% hint style="danger" %} J1850 information below is specific to M2 (Arduino) and needs updating {% endhint %} **J1850 PWM** is typically found in older Ford vehicles and operates at 41.6 kb/s. The bus is active when `J1850+_BUS` is pulled HIGH to 5V and `J1850-_BUS` is pulled LOW to 0V. **J1850 VPW** is typically found in older GM vehicles and operates at 10.4 kb/s. The voltage range for each protocol is different (0-7V for VPW and 0-5V for PWM). To change between the levels required for PWM and VPW variants of J1850, use this signal: `J1850_PWM_VPW` (P1 board signal name "J1850\_PWM\_nVPW") This signal is connected to physical pin 123 (PB8) of the SAM3X. Make this pin HIGH for PWM and LOW for VPW The following code that will both turn on power to J1850 circuit AND set level for either PWM or VPW: ```cpp void setup() { pinMode(PS_J1850_9141, OUTPUT); pinMode(J1850_PWM_VPW, OUTPUT); digitalWrite(PS_J1850_9141, HIGH); // LOW = no power at +12V_SW/+5V_SW // HIGH = power at +12V_SW/+5V_SW digitalWrite(J1850_PWM_VPW, HIGH); // LOW = ~7.9v (VPW) // HIGH = ~5.9V (PWM) } void loop() { } ``` These signals originate from the vehicle: `J1850+_BUS` connects to pin 2 on the OBD2 port and is used by **BOTH** J1850 PWM and VPW. `J1850-_BUS` connects to pin 10 on the OBD2 port and is used by J1850 PWM These signals connect to the processor as OUTPUTS: `J1850P_TX` (P1 board signal name "J1850+\_TX") is an OUTPUT from the processor used for BOTH J1850 PWM and VPW. "J1850+\_TX" is connected to pin 45 or PC18. This corresponds to the **PWMH6** on peripheral B. * *With J1850\_PWM\_VPW = HIGH (i.e. PWM mode):* When this signal goes HIGH , pin 2 of the OBD2 connector is 5.5V. When this pin is LOW, pin 2 of the OBD2 connector is 0V. * *With J1850\_PWM\_VPW = LOW (i.e. VPW mode):* When this signal goes HIGH , pin 2 of the OBD2 connector is 7.5V. When this pin is LOW, pin 2 of the OBD2 connector is 0V. `J1850N_TX` (P1 board signal name "J1850-\_TX") is an OUTPUT from the processor and is used for J1850 PWM. "J1850-\_TX" is connected to pin 7 or PC23. This corresponds to the **PWML6** on peripheral B. * *With J1850\_PWM\_VPW = HIGH (i.e. PWM mode):* When this signal goes HIGH , pin 10 of the OBD2 connector is 0V. When this pin is LOW, pin 10 of the OBD2 connector is 5V. PWMH6 and PWML6 functionality is described in section 38: Pulse Width Modulation (PWM) of the SAM3X [datasheet](http://www.atmel.com/Images/Atmel-11057-32-bit-Cortex-M3-Microcontroller-SAM3X-SAM3A_Datasheet.pdf). These signals connect to the processor as INPUTS: `J1850_PWM_RX` is an INPUT to the processor. "J1850\_PWM\_RX" is connected to pin 3 or PC28. This corresponds to the **TIOA7** on peripheral B. `J1850_VPW_RX` is an INPUT to the processor. "J1850\_VPW\_RX" is connected to pin 4 or PC26. This corresponds to the **TIOB6** on peripheral B. TIOB6 and TIOA7 functionality is described in section 36: Timer Counter (TC) of the SAM3X [datasheet](http://www.atmel.com/Images/Atmel-11057-32-bit-Cortex-M3-Microcontroller-SAM3X-SAM3A_Datasheet.pdf). # Power Supply Note A note regarding a non-obvious aspect of the P1's power supply P1 contains a "Synchronous Step-Down Converter" ([TPS54328](https://www.ti.com/lit/ds/symlink/tps54328.pdf?ts=1593196956435\&ref_url=https%253A%252F%252Fwww.google.com%252F)) whose purpose is to convert the vehicle voltage from the OBD-II port (12+ V) to 5 V for use by the PocketBeagle. This converter's enable pin was originally connected to a pin on PocketBeagle that floats when the device is powered off. The result is an unpredictable state on the enable pin which results in the P1 not reliably powering on through the OBD-II connector. This issue is limited to situations where power is only supplied through the OBD-II connector, powering through the USB connector should be unaffected. The currently implemented solution is the removal of the R7 resistor which connects the enable pin to PocketBeagle, which means the converter will always power on. **P1 is shipped with this fix in place.** ![Microscope image of where R7 resistor is removed](/files/-MAlxvxCK9cQZFHNIxcE) # OBD3way Docs Multipurpose OBD2 development test board The OBD2 test board is designed to simplify OBD2 device development. ![Typical setup: M2 is acting as an emulator while developing A0 code.](/files/-MA7TmQYi1PKjKDqTmCH) {% hint style="info" %} To purchase, click here: {% endhint %} ## Components The OBD2 test board has several components as shown below: ![](/files/-MA7gBGWZsstZ_4du32h) **INPUT OBD2 Connector:** 1 input OBD2 connector (MALE pins). This connector would plug into an OBD2 extension cable and eventually into a car's OBD2 port. **OUTPUT OBD2 Connectors:** 2 output connectors. (FEMALE pins). These connectors are the same as found in any modern car. **12V Input power source:** Use in external 12V power adapter when doing desktop OBD2 development. If OBD2 extension cable is used, you'll get power from the car and won't need the external power source. **Power jumpers:** Control power to each output by installing Jumpers. GREEN LED confirms power is ON. **Junction blocks:** Route OBD2 signals to the connectors as needed. All signals are broken out and available. More about Junction block functionality below. **CAN termination resistors:** 2 sets of termination resistors are available. These are typically used when using an emulator. ## Junction blocks The junction blocks near both OUTPUT OBD2 connector gives you the flexibility to change how signals move between connectors. Install a jumper wire between rows to make "through" connections, or jump over to other pins to rearrange signals. {% hint style="warning" %} Warning - be careful when rearranging signals between OBD2 connectors. Not all pins have same voltage levels. {% endhint %} The row closest to the OBD2 connector goes directly to the connector. The row farthest from the OBD2 connector goes directly to the INPUT OBD2 connector. ![](/files/-Lxw557YMl4TaBxGHnkF) Note: Ground is already connected between the 3 OBD2 connects, but also available on junction blocks for convenience. ## CAN Termination Blocks The two CAN termination blocks allow termination and connection of two different CAN networks simultaneously. ![Wiring schematic for each CAN termination block](/files/-MA7gBGVHrAgKeZdc9GC) ## Modes The OBD2 test board can function in several "modes" by rearranging how the signals route throughout the board. For example: #### 1. Sniffer: This mode allows you to use external test equipment to watch traffic. In the example below, the CAN0 channel is being "Sniffed". ![](/files/-MA7gBGOzJWUtMJawjA0) #### 2. Man in the middle: Put an OBD2 device (i.e. M2) in between the host and another OBD2 device (i.e. OEM scanner, etc). This mode gets its name from the computer security term. Learn more here: {% embed url="" %} In our case, if we wanted to intercept, change or better understand a CAN conversation, we'd use the connections shown below. The CAN traffic *to* and *from* "Scanner" would need to go *though* our device (shown in the middle as "man" below). ![](/files/-MA7gBGTgmToGDte2GFS) #### 3. Emulator: Connect 2 OBD2 dongles together for desktop development purposes. Typically, one of the devices would be set up to be an Emulator and the other a scanner, etc. In many cases, you'd need to ensure the CAN bus is terminated as shown below ![](/files/-MA7gBGUxczWEHP0NRF6) #### 4. Other: The OBD2 test board has several modes and many configurations - all of which can be made using standard jumper wires. For example, breakout or splitter modes are easy to do with the OBD2 test board. ## **Schematic and board files** We've put the schematics and board files into a Github repo. Feel free to create an issue with suggestions, bugs, etc. here: {% embed url="" %} # A0 Projects An overview of some projects currently available for use on A0 ## A0RET A0RET comes preinstalled on A0, it allows ELM327 emulation and wireless car-hacking with SavvyCAN. {% embed url="" %} ## A0 CAN Vehicle Data This project uses A0 to query the vehicle for speed, engine RPM, and coolant temperature and prints the data to the serial console. {% embed url="" %} ## A0 CAN Point to Point This project aims to familiarize users with basic CAN functionality on A0 by echoing CAN frames, great when paired with an M2 and OBD3way board. {% embed url="" %} ## A0 WIP Projects Find experimental projects here, or just inspiration for your own next big project! {% embed url="" %} # A0 CAN Vehicle Data Use A0 to read vehicle data. #### Items Used * 1x [A0](https://www.macchina.cc/catalog/a0-boards/a0-under-dash) * 1x Car with OBD-II port {% hint style="info" %} This project should also be natively supported on M2, however you could also add functionality to write the results to a .CSV file via the onboard SD slot, giving similar functionality to the P1 version of this project! {% endhint %} #### A0 Sketch Upload:point\_right:[THIS SKETCH](https://gist.github.com/kenny-macchina/f87e4c39e29a39562e168b9869d64ef8) to your A0, which queries the vehicle for speed, engine RPM, and coolant temperature, and prints the results to the serial monitor. It requires two libraries, which can be found:point\_right:[here](https://github.com/collin80/esp32_can) and:point\_right:[here](https://github.com/collin80/can_common). #### Vehicle Setup Plug A0 into the OBD-II port found beneath the dashboard (usually between the steering wheel and pedals, by your left knee). Keep A0 connected to your computer with the USB cable and open the Arduino IDE's serial monitor at baud 115200. #### Test Try revving your engine and watch as the RPM updates in the serial monitor. You can also try driving and watching the vehicle speed and engine coolant temperature. {% hint style="danger" %} Always focus on driving! {% endhint %} #### Example Data ![These graphs were made by copying the output from the serial monitor and using Excel's text import tool.](/files/-MA7WPHZqoH-t3cExFmD) ![](/files/-MA7WTEQgvxTG5lbBuq9) # A0 CAN Point to Point Send and receive CAN frames between an A0 and an M2. #### Items Used * 1x [A0](https://www.macchina.cc/catalog/a0-boards/a0-under-dash) * 1x [M2](https://www.macchina.cc/catalog/m2-boards/m2-under-dash) * 1x [OBD3way board](https://www.macchina.cc/catalog/tools/obd3way) * 1x 12V power supply #### M2 Sketch Upload [THIS SKETCH](https://gist.github.com/kenny-macchina/690d95b6c260b15f794510dccb4950c8) to your M2, which sends a CAN frame on CAN0 or CAN1 when you push switch 1 or 2, respectively. M2 will also blink a light when it receives a CAN frame on either channel. #### A0 Sketch Upload [THIS SKETCH](https://gist.github.com/kenny-macchina/5a39add47c97a8fcd16d0d45d8794679) to your A0, which sends a CAN frame on CAN0 when it first turns on, then waits and echos back messages it receives. It requires two libraries, which can be found [here](https://github.com/collin80/esp32_can) and [here](https://github.com/collin80/can_common). #### OBD3way Setup Connect both M2, A0, and OBD3way board as shown below. This connects the CAN0 of A0 to the CAN0 of M2. ![](/files/-MA7TmQYi1PKjKDqTmCH) ![CAN0 on the left is connected to CAN0 on the right.](/files/-MA7TmQeQ8OsMYMv98nn) #### Test Try hitting the reset button on the A0, upon waking up it will send a CAN frame on CAN0 and the M2 should flash, signifying it has received the frame. Then try sending a frame from the M2 to the A0, the A0 should echo it back to the M2 and it should flash again. # A0 CAN Read VIN Use A0 to read the VIN from a vehicle. Items Used * 1x [A0](https://www.macchina.cc/catalog/a0-boards/a0-under-dash) * 1x Car with OBD-II port #### A0 Sketch Upload :point\_right: [THIS SKETCH](https://github.com/macchina/A0_Read_VIN/) to your A0, which queries the vehicle‘s Vehicle Identification Number (VIN), and prints the result to the serial monitor. It requires two libraries, which can be found :point\_right:[here](https://github.com/collin80/esp32_can) and :point\_right:[here](https://github.com/collin80/can_common). #### Vehicle Setup Plug A0 into the OBD-II port found beneath the dashboard (usually between the steering wheel and pedals, by your left knee). Keep A0 connected to your computer with the USB cable and open the Arduino IDE's serial monitor at baud 115200. #### Test Watch the serial monitor. It should print out the VIN of your vehicle. #### How It works The Vehicle Identification Number (VIN) can be read from a vehicle using standard OBD-II commands. Several messages must be exchanged because the VIN is too long to fit in a single 8-byte CAN frame. Standard OBD services are defined in ISO 15031-5. `Service 09 - Request vehicle information` allows requesting the VIN. The network protocol used to split this request over multiple CAN frames is defined in ISO 15765-2. The sequence of messages used to read a VIN is as follows: `0x7DF | 02 09 02` A0 sends message from functional request ID 0x7DF. It is a SingleFrame with length of 2 (02). It is a request for the Request vehicle information service (09). The InfoType is VIN (02). `0x7E8 | 10 14 49 02 01 31 4D 38` Response from ECU #1. It is a FirstFrame with length of 20 (10 14). It contains the first 3 characters of the VIN “1M8” (31 4D 38). `0x7E0 | 30 00 00` A0 sends message using ECU #1 request address. It is a FlowControl frame with status ContinueToSend (30). The BlockSize value tells the ECU to send all remaining frames (00). The SeparationTime is 0ms (00). `0x7E8 | 21 47 44 4D 39 41 58 4B` `0x7E8 | 22 50 30 34 32 37 38 38` The ECU responds with two ConsecutiveFrame messages with sequence numbers 1 (21) and 2 (22). Each contains seven more characters of the VIN. The VIN can then be assembled by combining the characters from each of three frames sent by the ECU: 31 4D 38 47 44 4D 39 41 58 4B 50 30 34 32 37 38 38, which translates to 1M8GDM9AXKP042788 in ASCII.\
# Work-in-Progress A0 projects Below are longer-term projects specific to A0. The goal here is to help you get started and get inspired! These are community-developed, open source projects, so we encourage you to get involved. {% hint style="info" %} For basic tutorials, check out our mini tutorial section including several A0 specific projects: [projects/mini-project-tutorials](/projects/m2-projects/mini-project-tutorials) {% endhint %} ## A0 as a Webserver - a digital dashboard! :timer::control\_knobs: With the right code, A0 can be a WIFI access point hosting a webpage - not just some boring static website, but a fully dynamic, interactive website where any browser (laptop, tablet, cell phone) can be your digital dashboard! At the heart of A0 is the powerful ESP32 microcontroller capable of interacting with the car via CAN and be a fully functional WIFI access point at the same time. You connect your phone to the A0 access point, pull up a browser and start interacting with your car. In this demo, we are displaying Boost pressure in a sweet 2016 Ford Fusion by reading the Intake MAP value via OBD2 commands, subtracting the ambient pressure (hard-coded to whatever it was here in MN during our test) and spitting out websocket messages at 20Hz. We're also demonstrating how to send data to the A0 to toggle an LED via a button press on the phone. This demo was hacked together starting with this project as a reference: The webpage hosted on the ESP32 has a gauge.js instance running and a Bootstrap CSS framework. To add more gauges, we'd need to start using JSON messages (or something similar) to update more than one gauge. ![](/files/-M4PZmi2UkQqRpr842EY) Here is the code we used in this demo: {% embed url="" %} ### Next steps: This demo shows a basic implementation of how to use websockets to display a single gauge on a browser. Next step would be to add more gauges, line graphs, and improve user interface. {% hint style="success" %} Get in touch if you want to help take this project forward! {% endhint %} ## AWS integration :spider\_web: Put your data in the cloud. We'll be posting more information here about some cloud projects. ## Other Projects ideas: 1. BLE beacon 2. Bluetooth to phone connection. 3. [OBD-II emulation on ESP32 ](https://hackaday.com/2018/04/11/emulating-obd-ii-on-the-esp32/) # M2 Projects An overview of some projects currently available for use on A0
# "OK Google, start my car!" Remotely start and stop a car using M2 with SuperB! {% embed url="" %} **Hardware Needed:** * [M2](https://www.macchina.cc/catalog/m2-boards/m2-under-dash) * [SuperB](https://www.macchina.cc/catalog/m2-accessories/superb) * Smartphone with Google Assistant * GM Vehicle (GM CAN messages provided, you'll need to find your own for non-GM vehicles) **Services Needed:** * Google Assistant * [If This then That (IFTTT)](https://ifttt.com/join) * [Adafruit IO](https://io.adafruit.com/) ## Theory ![Flowchart showing the relationship between hardware and services used](/files/-Lhg6FTJh8YbkrwwlB-0) * Voice commands will be given to either a smartphone or a Google Home device * Voice data is passed to Google Assistant * Google Assistant then triggers IFTTT with either an ON or OFF command * IFTTT in turn updates Adafruit IO with the ON or OFF command * SuperB receives the ON or OFF command and updates itself to reflect the new state * M2 reads the ON/OFF state of SuperB and then starts or stops the car ### Implications, Expansion * Other than Google Assistant, IFTTT supports a huge number of triggers. (e.g. weather, connect/disconnect from Wi-Fi networks, time, etc.) For example, have your car warm up before leaving for work if the temperature is below a certain threshold. * Because the smartphone and SuperB are never directly connected, commands can be sent to the vehicle as long as both devices have an internet connection, regardless of the physical distance between them. ## Google Assistant You'll need either a smartphone capable of accessing Google Assistant or a Google Home device. In either case, make sure you know the credentials of the Google account associated with the device. ## If This then That (IFTTT) If This then That will handle the exchange between Google Assistant and Adafruit IO, and adds the option to use a trigger other than a voice command. Register for an account [here.](https://ifttt.com/join) Make sure to link the same Google account used on your smartphone or Google Home. ## Adafruit IO Adafruit IO is an easy to use web service that can control internet enabled hardware (like M2 and SuperB). IO provides a virtual dashboard accessible through a web browser onto which all manner of gauges, sliders, buttons, and switches can be placed. For our purposes we'll have a dashboard with a simple ON/OFF switch, the state of which the SuperB will be able to read. What makes IO extremely useful is that these switches can be controlled by other web services like IFTTT, and not just through the web dashboard. Register for an account [here.](https://io.adafruit.com/) ## Step 1: Set up Adafruit IO Create a new feed titled "LED\_Control". (case-sensitive!) ![How to create a feed](/files/-Lhg6FTLgBX-Lk0T3Irr) ![How to create a feed](/files/-Lhg6FTNUFrik8xOpaPS) Create a new dashboard with any title. ![How to create a dashboard](/files/-Lhg6FTPikqpSNxjgr_U) Navigate to the new dashboard and place a toggle switch linked to the "LED\_Control" feed. Leave the block settings on their default settings. ![How to create a toggle switch](/files/-Lhg6FTR4ZjBFKJ3eqk_) ![How to create a toggle switch](/files/-Lhg6FTTI97XBP7kxrwV) ![Settings for the toggle switch](/files/-Lhg6FTVImavmTetJ26J) There should now be a single toggle switch on the dashboard: ![The switch on the dashboard](/files/-Lhg6FTXzS5RbOZmgaP9) Find and record your username and key, which will be necessary later. ![Where to find username and keyimage showing where to find username and key](/files/-Lhg6FTZPOdnHEtzLUHu) ## Step 2: Set up and Test SuperB Download the SuperB sketch [here.](https://github.com/kenny-macchina/Ok-Google-Start-My-Car/tree/master/SuperB_Sketch) (This sketch uses the Adafruit MQTT library which can be installed through the Arduino library manager) Update the sketch with your Adafruit IO and Wi-Fi credentials. ![Where to update credentials in sketch](/files/-Lhg6FTakhXSVz5CVkwm) To flash SuperB with M2 follow the instructions [here.](http://docs.macchina.cc/superB/flashing/arduinoM2.html) Alternatively, if you have an XBee USB adapter board you can flash SuperB using the instructions found [here.](http://docs.macchina.cc/superB/hardware.html#use-xbee-usb-adapter-to-flash) Power on SuperB (either with an M2 or USB adapter board) and use the Adafruit IO dashboard to test the functionality. ![SuperB responding to Adafruit IO dashboard](/files/-Lhg6FTc5tSo5JKVB_C3) ## Step 3: Set up and Test IFTTT Create a new applet with Google Assistant as the trigger (the "this").
Google Assistant in IFTTT
Select Adafruit IO as the action (the "that"). Connect your Adafruit account to IFTTT if prompted. Select the "LED\_Control" feed and enter "ON" (case-sensitive) as the data to save to the feed. ![Adafruit IO in IFTTT](/files/-Lhg6FTgQC-ST0ucoUmE) In the same style create another applet to turn the car off, sending "OFF" instead of "ON". With these 2 applets you should now be able to control the toggle switch on your IO dashboard via Google Assistant. ![The 2 applets just created](/files/-Lhg6FTiBfslIBYVUlj4) ![Google Assistant controlling Adafruit IO and SuperB](/files/-Lhg6FTkKCw_FizVIqUS) Great! At this point we can toggle a pin on SuperB using Google Assistant. The final step is to have M2 read the pin state and then perform an action on the car accordingly. If you're interested in using more than just one pin the SuperB pinout can be found [here,](/product-documentation/superb-docs/hardware) and the pinout for the M2's XBee socket can be found [here.](/product-documentation/m2-docs/detailed-reference/pin-mapping#xbee) ## Step 4: Flash M2 Download the M2 sketch [here.](https://github.com/kenny-macchina/Ok-Google-Start-My-Car/tree/master/M2_Sketch) This sketch uses the M2\_12VIO library found [here,](https://github.com/TDoust/M2_12VIO) the pwm library found [here,](https://github.com/antodom/pwm_lib) and the mcp2515 library found [here,](https://github.com/macchina/Single-Wire-CAN-mcp2515) make sure you have them installed. Determine which version of M2 you have [here.](/product-documentation/m2-docs/versions) Comment out the V4 specific line in the readBatteryVoltage() function if you have V3 or earlier, otherwise leave the code as is. ![Code to modify for different versions of M2](/files/-Lhg6FTmPH7sC0LeJ9J4) The startCarSpecific() and stopCarSpecific() functions are pre-populated with GM specific CAN messages. You'll have to determine what CAN messages to send for other cars. (This may take some work to determine!) ![Start and stop functions](/files/-Lhg6FTosT2WFN8q_Ny6) # M2 and SavvyCAN, the Basics SavvyCAN is a CAN bus reverse engineering and data capture tool. It allows you to use M2 to send and receive CAN messages both to and from a car. {% embed url="" %} ## Hardware Needed * [Macchina M2](https://www.macchina.cc/catalog/m2-boards/m2-under-dash) * [USB Cable (The longer the better)](https://www.macchina.cc/catalog/cables/usb-micro-b-20-cable-5-pin-2824awg-gold-plated-black-15ft) * Laptop * Test Vehicle ## Flash M2 with M2RET M2RET must be flashed to M2 to forward messages from the car to the computer and vice versa. The easiest way to install M2RET is by downloading the M2RET firmware updater from the SavvyCAN website, the updater can be found [here.](http://www.savvycan.com/M2RET_Flash.zip) Extract "M2RET\_FLASH.zip" and follow the instructions in the "HOWTO.txt" file relevant to your operating system. (Make sure M2 is plugged in and any existing serial connections to it are closed) Screenshots are shown below: {% tabs %} {% tab title="Windows" %} ![](/files/-LioCIq2zq5Ps955f3jQ) {% endtab %} {% tab title="OSX" %} {% endtab %} {% tab title="Linux" %} {% endtab %} {% endtabs %} Source code for M2RET is here: {% embed url="" %} ## Connect M2 with SavvyCAN Download the SavvyCAN version appropriate for your operating system [here.](http://www.savvycan.com/) {% hint style="info" %} Disconnecting and reconnecting M2 to the computer after flashing can fix some issues where M2 cannot connect to SavvyCAN {% endhint %} * **1)** Open the connection window. ![](/files/-LioJxR5g5_DSMALML7J) * **2)** Click "Add New Device Connection" and create a new serial connection with the relevant port. ![](/files/-LioLCOBnefMCH4WqL19) * **3)** Test the connection by opening Send Frames>Fuzzing. Click "Start Fuzzing". ![](/files/-LioO3PZC0vpRdpAN_6P) ![Success! M2 lights up and blinks according to the fuzz rate](/files/-LioRbh0hf15XFWoREXn) ## Use M2 and SavvyCAN on a Vehicle {% hint style="danger" %} Always be safe when working on or around vehicles and use common sense. {% endhint %} * **1)** Now close the fuzzing window and plug M2 into the OBDII port of a turned off vehicle. SavvyCAN will begin displaying the CAN frames received from the vehicle. ![](/files/-LisPrXLeVNYTCHprwc6) * **2)** Now try starting the vehicle and observe the increase in CAN traffic. (For a more coherent view try checking the "Overwrite Mode" box) ![](/files/-LisRzyCbmGMWLB9Q07I) * **3)** In addition to enabling "Overwrite Mode", individual frames can be filtered by ID using the check boxes on the right side of the screen. This can be useful for determining which IDs are associated with certain actions in the car. {% hint style="info" %} For more information on using SavvyCAN, try [the SavvyCAN docs](http://www.savvycan.com/docs/), [Collin Kidder's YouTube channel](https://www.youtube.com/user/CKidder80), or [the Macchina forums](https://forum.macchina.cc/). {% endhint %} # Help Collect Voltage Data How can we tell when the engine is actually turned on? Many people have done it before or known someone who's done it: leaving your headlights on and coming back to a dead battery. When developing electronic devices for cars a similar problem can occur with high power devices such as cellular modems. Therefore it would be advantageous to keep the high power devices off until the car is turned on, which raises the question, how can we tell when the car is turned on? We've started a little project to collect voltage measurements before, during and after a car engine is running. Click here to learn more and contribute: {% embed url="" %} Here is a sample of the voltage levels during the 3 stages of starting a car: ![](/files/-LobKtympIrLo6YB9s9p) # Mini-Project Tutorials You made an LED blink, now what? These mini-projects serve to lessen the gap in knowledge between a simple LED blinking sketch and more advanced projects. Complete these to gain a better understanding of the P1, M2, A0, and OBD3way! ![](/files/-MBjT9hRQXM3n1pptgFx) # M2 CAN Loopback Send a CAN frame on CAN0 and receive it on CAN1, and vice versa. #### Items Used * 1x [M2](https://www.macchina.cc/catalog/m2-boards/m2-under-dash) * 1x [OBD3way board](https://www.macchina.cc/catalog/tools/obd3way) #### M2 Sketch Upload [THIS SKETCH](https://gist.github.com/kenny-macchina/690d95b6c260b15f794510dccb4950c8) to your M2, which sends a CAN frame on CAN0 or CAN1 when you push switch 1 or 2, respectively. M2 will also blink a light when it receives a CAN frame on either channel. #### OBD3way Setup Connect M2 and OBD3way board as shown below. This connects M2's CAN0 to CAN1, hence "loopback". ![](/files/-MA7SH0AkUkRPAbeKKYn) ![CAN0 is connected to CAN1.](/files/-MA7T2tQUlyQvGJkmbS9) #### Test Try sending a CAN frame on both CAN0 and CAN1; the M2 LED should blink after each time signifying it has received its own message! (The M2 sketch also includes serial printouts, keep your M2 connected to your computer and open the Arduino IDE's serial monitor at baud 115200 to view these messages.) # M2 CAN Point to Point Send a CAN frame between 2 M2's. #### Items Used * 2x [M2](https://www.macchina.cc/catalog/m2-boards/m2-under-dash) * 1x [OBD3way board](https://www.macchina.cc/catalog/tools/obd3way) * 1x 12V power supply #### M2 Sketch Upload [THIS SKETCH](https://gist.github.com/kenny-macchina/690d95b6c260b15f794510dccb4950c8) to your M2, which sends a CAN frame on CAN0 or CAN1 when you push switch 1 or 2, respectively. M2 will also blink a light when it receives a CAN frame on either channel. #### OBD3way Setup Connect both M2s and OBD3way board as shown below. This connects the CAN0 of one M2 to the CAN0 of the other. ![](/files/-MA7TLwS8h132dIR5i9q) ![CAN0 on the left is connected to CAN0 on the right.](/files/-MA7TRSqSQS8Pq69LrRY) #### Test Try sending a CAN frame from one M2 to the other; pushing the button on one M2 should cause the other M2 to blink, signifying it has received the frame! You can also try rerouting the jumpers to send between the different CAN channels. (The M2 sketch also includes serial printouts, keep your M2 connected to your computer and open the Arduino IDE's serial monitor at baud 115200 to view these messages.) # M2 SWCAN Point to Point Send a SWCAN frame between 2 M2's. #### Items Used * 2x [M2](https://www.macchina.cc/catalog/m2-boards/m2-under-dash) * 1x [OBD3way board](https://www.macchina.cc/catalog/tools/obd3way) * 1x 12V power supply #### M2 Sketches Upload [THIS SKETCH](https://gist.github.com/kenny-macchina/13044469072597d928c02c67c39678fa) to one M2, and [THIS SKETCH](https://gist.github.com/kenny-macchina/55bda591e825ab0b52390a91e1b89962) to the other. The first sketch is the transmitter and sends a non extended frame and blinks a light quickly when button 1 is pressed, and sends an extended frame and blinks a light slowly when button 2 is pressed. The second sketch is the receiver and prints any SWCAN frames it receives to the serial monitor. It also blinks an LED corresponding to whether or not the frame is extended. Both sketches are based on the SWCAN MCP2515 library which can be installed from the link below: {% embed url="" %} #### OBD3way Setup Connect both M2's and OBD3way board as shown below. This connects the SWCAN of one M2 to the SWCAN of the other. ![Use a single jumper to connect the SWCAN pins on both M2's.](/files/-MFfumP5kvN9iXdRB2ko) #### Test Try pressing button 1 on the transmitter M2; both it and the other M2 should blink quickly as the frame is sent and received, respectively. If your receiving M2 is connected to a serial monitor the frame data will be printed there as well. Try pressing button 2 to send an extended frame. The same thing should happen with a slower blink indicating an extended frame. # M2 VIN Extraction Use M2 to read a Vehicle Identification Number (VIN) and write it to an SD card. #### Items Used * 1x [M2](https://www.macchina.cc/catalog/m2-boards/m2-under-dash) * 1x Car with OBD-II Port #### M2 Sketch Upload [THIS SKETCH](https://gist.github.com/kenny-macchina/16db4b58defc7fd6edb0fd844adc4448) to your M2, which queries the vehicle's Engine Control Unit (ECU) for the VIN and then writes it to a text file via the onboard SD slot. #### Sketch Libraries The sketch above makes use of multiple libraries, install them through the links below: {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} #### Collect VIN With the vehicle running, plug M2 into the OBD-II port. M2 should flash yellow lights as it queries for the VIN, then light up green for success or red for failure. In either case pressing button 1 will make M2 try again, writing a new text file each time. # P1 Projects An overview of some projects currently available for use on A0 # P1 CAN Vehicle Data Use P1 to read vehicle data and export it to a CSV file. #### Items Used * 1x [P1](https://www.macchina.cc/catalog/p1-boards/p1-under-dash) * 1x Car with OBD-II port #### Download P1 Vehicle Data Python Program After connecting to P1 via SSH, run the command below to download the python program and save it to \~/scripts. (If using putty to SSH, just right click to paste!) ``` wget -P ~/scripts https://gist.githubusercontent.com/kenny-macchina/cf47daf663f9091460fc3454f5e38de9/raw/676f2a36f300fa8e5c9c43c05a7bc18af2479b5c/p1_data.py ``` ![Downloading the python program](/files/-MBdsXg6Y2fBvKroH5dG) #### Install Pip Run the commands below to install the "Pip" package manager and reboot. ``` curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py python get-pip.py sudo reboot now ``` ![Installing Pip, curl and reboot not shown.](/files/-MBeBM6Egbq-GPjrOMCY) #### Install Python-CAN Library Run the commands below to install the python-can library and reboot. ``` pip install python-can sudo reboot now ``` ![Installing python-can, reboot not shown.](/files/-MBeBClG2gqUeVufii_3) #### Collecting Data First, start your car, then plug P1 into the OBD-II port and run the data collection program using the command below. (Make sure you're in the home directory beforehand by running the command "cd".) P1 will prompt for a password as the program sets up the CAN0 bus. After entering the password data collection will begin until the program is halted by pressing CTRL-C. ``` python scripts/p1_data.py ``` ![Terminal while data collection is running](/files/-MBeFexvWZz3AKtqF_30) #### Retrieving Data To download the CSV file from P1, the command below can be used to host an HTTP server on the port specified, this can then be visited in a web browser (from a computer on the same LAN) and the file(s) downloaded. ``` python3 -m http.server 1337 ``` ![Hosting the HTTP server](/files/-MBeFvlVRh_WMpX2d0vJ) ![Retrieving the file from a browser](/files/-MBeG7bEBQ8mB-Rmc2_8) #### Example Results ![Vehicle and engine speed for a short drive around the block](/files/-MBeNJTbNzjnbtIppcuA) ![Coolant temperature from the same test drive](/files/-MBeNMyQnUQ6wm6aYnjJ) # P1 CAN Loopback Send a CAN frame on CAN0 and receive it on CAN1, and vice versa, but this time with P1! #### Items Used * 1x [P1](https://www.macchina.cc/catalog/p1-boards/p1-under-dash) * 1x [OBD3way board](https://www.macchina.cc/catalog/tools/obd3way) * 1x 12V power supply #### OBD3way Setup CAN0H to CAN1H and CAN0L to CAN1L and place a termination resistor across these connections; see photos below for setup. ![](/files/-MAXIu_6aYjLrnGBrEKH) ![](/files/-MAXJ0QKUg-3gM8MdAL4) #### Test Once everything is hooked up, we power up P1, and SSH into P1 in two windows at: 192.168.7.2 to control each CAN channel at the same time. ![](/files/-M2nt2kcKHvosmgl3PF7) Below you can see each session. Note that you'll want to send the "candump ..." command before sending the "cansend ..." command in the other window. {% tabs %} {% tab title="CAN0 Terminal" %} ``` login as: debian Pre-authentication banner message from server: | Debian GNU/Linux 9 | | BeagleBoard.org Debian Image 2019-08-03 | | Support/FAQ: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian | | default username:password is [debian:temppwd] | End of banner message from server debian@192.168.7.2's password: The programs included with the Debian GNU/Linux system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright. Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law. debian@beaglebone:~$ sudo ip link set can0 type can bitrate 250000 [sudo] password for debian: debian@beaglebone:~$ sudo ifconfig can0 up debian@beaglebone:~$ candump can0 can0 01A [8] 11 22 33 44 AA BB CC DD can0 01A [8] 11 22 33 44 AA BB CC DD can0 01A [8] 11 22 33 44 AA BB CC DD can0 01A [8] 11 22 33 44 AA BB CC DD can0 01A [8] 11 22 33 44 AA BB CC DD can0 01A [8] 11 22 33 44 AA BB CC DD can0 01A [8] 11 22 33 44 AA BB CC DD can0 01A [8] 11 22 33 44 AA BB CC DD can0 01A [8] 11 22 33 44 AA BB CC DD can0 01A [8] 11 22 33 44 AA BB CC DD can0 01A [8] 11 22 33 44 AA BB CC DD can0 01A [8] 11 22 33 44 AA BB CC DD ^Cdebian@beaglebone:~cansend can0 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can0 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can0 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can0 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can0 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can0 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can0 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can0 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can0 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can0 01a#11223344AABBCCDD debian@beaglebone:~$ ``` {% endtab %} {% tab title="CAN1 Terminal" %} ``` login as: debian Pre-authentication banner message from server: | Debian GNU/Linux 9 | | BeagleBoard.org Debian Image 2019-08-03 | | Support/FAQ: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian | | default username:password is [debian:temppwd] | End of banner message from server debian@192.168.7.2's password: The programs included with the Debian GNU/Linux system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright. Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law. debian@beaglebone:~$ sudo ip link set can1 type can bitrate 250000 [sudo] password for debian: debian@beaglebone:~$ sudo ifconfig can1 up debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ cansend can1 01a#11223344AABBCCDD debian@beaglebone:~$ candump can1 can1 01A [8] 11 22 33 44 AA BB CC DD can1 01A [8] 11 22 33 44 AA BB CC DD can1 01A [8] 11 22 33 44 AA BB CC DD can1 01A [8] 11 22 33 44 AA BB CC DD can1 01A [8] 11 22 33 44 AA BB CC DD can1 01A [8] 11 22 33 44 AA BB CC DD can1 01A [8] 11 22 33 44 AA BB CC DD can1 01A [8] 11 22 33 44 AA BB CC DD can1 01A [8] 11 22 33 44 AA BB CC DD can1 01A [8] 11 22 33 44 AA BB CC DD ``` {% endtab %} {% endtabs %} # Community Projects We're keeping a list of community projects here. Please let us know if you'd like your project included. {% embed url="" %} Swiss army knife of Controller Area Networks (CAN) running on M2 {% endembed %} {% embed url="" %} Turn vehicle canbus logs into linked HTML based performance charts. {% endembed %} {% embed url="" %} J1939 tool using M2 {% endembed %} {% embed url="" %} Driving the E46 Cluster with Macchina P1 {% endembed %} ## Show off your project We are always interested in seeing what everyone is up. Please send us an email at # Project Support How to get the best possible help on you project ## How to get help If you have questions related to Automotive reverse engineering, CAN bus (or other protocols), or building your applications that leverage these technologies, please follow the below process. We want to help as much as possible and this is the best way to work with us and the community to build great projects. General Process: We want you to submit your questions to both us and the Reddit Carhacking community. This way we can try to help in a public searchable place, but also get as many qualified eyeballs as possible (in many cases we have no experience with the car you're working on but someone at r/CH will) so you get great answers and hopefully start a good discussion. Step 1: Fill out the below and submit it at * Make: (Ford, Toyota,...) * Model/Engine/trim: (Example: F-150, 5.4 V8, King Ranch) * Year: (what year is it!) * Description of your setup: (tools, wiring, include pictures...) * What are you trying to do: (example: roll my windows up on command, provide detail) * Context: (where are you stuck, what have you tried) * Relevant wiring diagrams: (I suggest including both the OEM and non OEM diagrams available from All-data. Try to include all the relevant systems computer data lines, DLC, and any target parts like the fuel pump.) * Attachments: relevant wiring diagrams, SavvyCAN logs, specific ECU details when applicable, Arduino or other sketches Step 2: Send us a link to the reddit post to , subject: Start Support We will share the link internally and add anything we can to the discussion. We try hard to provide as much support to these posts as possible. ### # Other Resources #### For everyone: * **Wiring diagrams:** Many car specific questions can be answered by looking at its wiring diagram. Anytime you ask someone for help you should try to include wiring diagrams. On newer cars where diagrams are often missing you often have to use an older year's diagrams, it's not ideal but it will do in a pinch (unless this is the first year of a new generation; check the car's Wiki page for generation year cut offs). * [**r/carhacking**](https://www.reddit.com/r/CarHacking/)**:** One of the best places to find like minded car nerds. This subreddit was actually started by Macchina M2 beta testers and has since grown into one of the best automotive electronics communities. With 20k subscribers you are pretty likely to find someone there who has tried to do what you are working on or at least has experience with the car you're working on. #### Developers and Engineers: * **Other documentation:** For example A0 uses the ESP32-WROVER-E - Espressif provides a great support network including documentation and data sheets that will help. Many people develop for A0 with the Arduino IDE, you will find good documentation and resources on their site. * **Macchina Dev Forum:** Lots of good information relevant to developing for Macchina products here. Do a quick search of the forum to see if your question was answered in there. (We know this is not an ideal place to find answers quickly. We are currently trying to move relevant information out of the forum and into the docs). * [CarHackingVillage:](https://www.carhackingvillage.com/) A group that travels to multiple conferences; usually security research and hacking related (e.g., DEFCON). They put on demonstrations, talks, competitions, and training. Great way to get hands on experience and meet knowledgeable people * [SAE international:](https://www.sae.org/) The organization that creates all of the J standards like J2534, J1939,... # Contact US / FAQ How Macchina approaches supporting user development with our products. {% hint style="danger" %} Macchina products can be used by a wide range of people for a wide range of tasks. As great as that is, it make supporting user development a challenge. Please keep in mind the below are the best practices we have come up with for trying to help as many people as possible with our small team. {% endhint %} ## Step 1 (start here) The first thing we need to do is try to identify the type of help you need and how to direct you within our company or community. * Are you **beginner** working on your first project and looking for advice? Go [here ](/projects/project-support) * Is our **documentation** missing something that would benefit many people? Go [here](#documentation-request) * Did you find an issue in a Macchina produced **library** or other related code? Go [here](#submit-a-github-issue) * If you are looking to **partner** with Macchina or have us work on your product? go [here](#business-questions) * Are you an **experienced engineer/developer** with a technical question hoping to talk with a Macchina Engineer? Go [here](#ask-a-macchina-engineer) * Do you have **shipping** related questions? (invoice, tracking,...) go [here](#shipping-related-questions) * If you're interested in a **bulk/resale** ordering, go [here](#bulk-orders) * For **custom** orders (you want something about the HW or FW changed). Go [here](#custom-orders) * For **defective or broken** products please. Go [here](#issues-returns) * Are you **outside the US** and looking to buy Macchina products? Go [here](#international-orders) * For questions on **lead times** for new restocking products go [here](/support-contact-us/out-of-stock-status) ## Documentation Request This is the easiest way to get support from us. If you think we are missing something from our docs, then please let us know and we will try to get it added. Please note that questions like "how do I tune my car" are not in scope for the documentation. Good examples include how to send a CAN message, how to blink an LED,... To submit a doc request please email us the below information to , * Subject: Doc Request * Relevant product SKU(s): * What are you trying to do: (please be detailed, this will help us understand the use case) * What document/tutorial would help you: (be specific) ## Submit a GitHub Issue If you found an issue that has to do with a specific library or code base, raise an issue in the appropriate repo here: {% embed url="" %} {% hint style="info" %} We are always looking for ways to engage the community and leverage everyone's collective knowledge to build better open source libraries, examples, and projects. Right now we are considering adding a bounty program. If you have experience with something like this or other community building methods please send us your thoughts to , Subject: Dev Community Feedback. {% endhint %} ## Business Questions For questions related to your business using Macchina products or support * Partnerships * Licensing designs * iOS authorization * Engineering services/looking for help Please reach out to us at , Please including all of the following: * Subject: Business w/ (your\_company\_name) * Company: (who do you work for) * Company size: (how many people are full time with your company) * Company description: (what does your company do) * Title/focus: (what would you say you do exactly?) * Description/question: (please be detailed - let us know how we can help) ## Ask a Macchina Engineer Schematics are available in the documentation. If you have a question you believe should have been answered by the technical documentation please submit a [doc request here](#documentation-request). If your question relates to car specific things such as reverse engineering CAN messages we ask that you use [this process](/projects/project-support#how-to-ask-for-help) to ensure you get the best possible help. If you have a technical question that only a Macchina engineer can answer (this generally relates to design decisions made by Macchina) then please submit the below to * Subject: Macchina Technical * Related Product: (Name, SKU) * Question: (technical question) * Context: (Please provide as much detail surround your question as possible) Please allow up to 2 weeks for us to respond. In some cases like if you have a question related to working with a processor in a Macchina product we may refer you to an appropriate FAE better suited to speak to their product lines. ## Shipping related questions Lead time: we try to ship within 7 business days Please remember we are small company, while we are trying to improve on shipping times we are not Amazon. If you have a critical date please reach out to us about expedited shipping options. (, Subject: Express Shipping) Tracking: if you are looking for your tracking information you should receive it in the shipping confirmation email. If you need an invoice changed or have another shipping related question please reach out to us (, Subject: Shipping - your order number ) ## **Bulk/Resale Orders** If you would like to order a Macchina product in bulk quantities. Standard lead time is 10 weeks from PO placement (or payment). For a new customer we require 100% payment prior to kick off. Requirements: * Only available for 100+ units (otherwise please use the in-store bulk discounts) * Assumes no changes to the design (otherwise scroll down to Custom Orders) Please email with the below information 1. Subject: Bulk Order Request 2. Product SKU(s): Tell us what product(s) you are interested in, please use SKUs 3. Quantity: Let us know how many you want in this order 4. Packaging: Choose bulk packaging or standard Macchina individual unit packaging 5. Requested Delivery Date: When do you need the order by 6. Requested discount: From MSRP 7. Other notes: Any other requests related to the project email the above to ## **Custom Orders** If you would like to make a bulk order of a Macchina product but you need changes made to the PCB, enclosure, firmware, or other aspects of the design. Requirements: * No MOQ * All custom orders will be produced by Macchina unless otherwise agreed on in a license agreement Process: 1. Email the below information to 2. For simple changes that can be finished in a day we will make a quote with the number of engineering or other hours required to make the changes. For larger changes (multi day) we will work off a time and materials contract. In either case you will be billed at our hourly consulting rate. 3. At this point we can estimate the cost of the final product 4. We will produce a sample/ first article at a flat rate determined after engineering 5. After you accept the first article we can place your first order, (based on CM pricing curves we suggest you target at least 500 unit runs) Please email with the below information 1. Subject: Custom Order Request 2. Product SKU(s): Tell us what product(s) you are interested in, please use SKUs 3. Use case: Describe your project 4. Changes: What changes do you think your project needs 5. Quantity: Let us know how many you want in this order 6. Packaging: Choose bulk packaging or standard Macchina individual unit packaging 7. Requested Delivery Date: When do you need the order by 8. Budget: Please help us understand your financial goals, it helps to consider max NRE and max unit price right away 9. Other notes: Any other requests related to the project email the above to ## Issues/Returns ### Defective products We don’t want to ship things that don’t work, so we test every unit before it leaves. That doesn’t mean customers never have issues, but it should be rare. If you are having an issue, please make sure you have eliminated the other possible causes (computer, cable, sd card, or other issues). If you still believe our hardware is the issue please reach out to us at , * Subject: Product Defect * Order Number: (from your purchase confirmation email) * Current address: * Issue Description: * Pictures: (if you see visable damage) We will send you a return label and get the replacement processed. ### Broken Sometimes you let the magic smoke out when trying to build cool things. We have seen people come up with interesting ways of accomplishing that. We like to see what happened. Please email (, Subject: Magic Smoke Issue) us pictures of the hardware (especially if you can see an obvious issue) and what you were doing with the hardware, this is mostly for future design planning. Most issues are not worth trying to fix. If we want to inspect the issue ourselves we will send you a return label. If you want to replace the unit we will offer you a one time discount code (unless you make a habit of this). ## International orders We prefer to do international shipping through our resellers. We are willing to ship [bulk orders](#bulk-orders) internationally, Sparkfun (Worldwide) Digi-Key (US only) Mouser (worldwide) crowdsupply (US only) # Common Issues ## Introduction In this section, we are collecting all of the common issues users come across, along with explanations and hopefully, solutions. If you don't see you answer here, we encourage you to look here to review: {% content-ref url="/pages/bN741FGUYsBh8kCxGkNc" %} [Contact US / FAQ](/support-contact-us/contact-us-faq) {% endcontent-ref %} or, if the issue has to do with a specific library or code base, raise an issue in the appropriate repo here: {% embed url="" %} ## Malfunction This is related to many problems we have seen - examples include A0 or M2 not reflashing correctly. We test every unit that ships to try to prevent this. While the ultimate solution varies from case to case the most common issue by far is a bad USB cable. It is not good enough to verify the cable works with another product as USB implementation and cable configuration vary. Please test with multiple cables. The one we verify with is available in our store. Drivers and worn out ports also frequently come up. ### **Arduino IDE Board Manager Issues** Description: After entering a new board manager URL in File->Preferences, going to Tools->Boards Manager causes a Java error. Upon closing, Arduino IDE will be unable to reopen until it is either reinstalled or the folder ...AppData/Local/Arduino15 is deleted. Solution: Ensure that Java is allowed network access in your computer's firewall settings. ### Why doesn't my SD card work? It may be fake. Description: We have had customers contact us regarding SD card problems with M2. On rare occasions it would seem that an SD card will flatly refuse to work with M2, without any apparent rhyme or reason. Sometimes they are unbranded generic cards and sometimes they are well-known name brands. Sometimes they are slower cards and sometimes they are faster cards. In all the time we have tracked complaints about SD card problems we have noticed one unifying theme: there is no unifying theme. Solution: That’s a little hard to believe, so we set out to do some random testing. We bought a handful of SD cards from a handful of vendors, and tested each card straight out of the packaging directly in M2. We also tested all of the cards on a Mac with an SD card reader, using “Disk Speed Test” by Blackmagicdesign. Of the six SD cards, two failed in M2 outright and posted extremely poor performance in Disk Speed Test. Both were Sandisk Ultra-branded and purchased from the same source, but another Sandisk Ultra purchased from a different source performed perfectly. It did not appear to be a question of class of card, which leads us to believe that the only way to get both failed cards to operate so poorly and nearly identically MIGHT be if the cards are fakes. The random internet budget vendor who sold us the suspect cards may not even be aware that they are selling counterfeits that don’t work in many applications. There are a LOT of good write-ups on the problem of counterfeit SD cards, but one that we found particularly detailed and useful is . TL;DR: There is almost nothing to prevent a customer from buying a fake card, so all you can do is buy from reputable sources with good return policies (such as the 8GB card we carry), and thoroughly test the card yourself! # Out of Stock/ Status We understand many people are looking for information on when Macchina products will be back in stock. This is the most up to date information on that regard. For those who are curious about our extended out of stock period, the short answer is we got hit by a number of issues all at once. COVID first caused parts shortages, then caused CMs to change strategies, both of which changed our business plans. Once products go to Production Start expect about 10 weeks until they are on shelves. Unfortunately no one in support will be able to offer any more detail than what is available here. Macchina - | Product | Status | Last updated | | ---------- | --------------------- | ------------ | | A0 | In Stock | 1/18/24 | | M2 | Sourcing review | 1/18/24 | | P1 | Hold (depends on M2) | | | OBD3way | First article testing | 1/16/24 | | SuperB (x) | bulk order available | 12/14/23 | | A4 | First article testing | 1/16/24 | | R1 | Sourcing review | 1/18/24 | Resellers | Reseller | Products | Status | | ----------- | -------- | ------------ | | Sparkfun | A0 | In stock | | Crowdsupply | M2/ SB | out of stock | | Mouser | M2/SB | out of stock | | Digikey | all | out of stock |