tinygo.org/x/drivers@v0.27.1-0.20240509133757-7dbca2a54349/wifinina/README.md (about)

     1  # WifiNINA Driver
     2  
     3  This package provides a driver to use a separate connected WiFi processor ESP32 for TCP/UDP communication.
     4  
     5  The way this driver works is by using the SPI interface of your microcontroller to communicate with the WiFi chip using the Arduino SPI command set.
     6  
     7  ## Using the WiFiNINA Driver
     8  
     9  For information on how to use this driver, please take a look at the examples located in the [examples/net](../examples/net) directory.
    10  
    11  ## Firmware
    12  
    13  **PLEASE NOTE: New Adafruit Boards with WiFi and Arduino Nano33 IoT and Nano RP2040 Connect boards most likely already have a recent version of the nina-fw firmware pre-installed. You should not need to install the firmware yourself.**
    14  
    15  In order to use this driver, you must have the [nina-fw firmware](https://github.com/arduino/nina-fw/) installed on the ESP32 chip. If it is already installed, you can just use it. You do not need to flash the firmware again unless it has known bugs or lacks functionality you plan to use.
    16  
    17  The following instructions are only for those who want or need to update the firmware on your board.
    18  
    19  ### Update Arduino Boards with Arduino IDE
    20  
    21  Probably, the easiest way to update nina-fw on Arduino boards is to use their IDE.
    22  Please see [tutorial page](https://www.arduino.cc/en/Tutorial/WiFiNINA-FirmwareUpdater) for detailed instructions.
    23  
    24  Sometimes you may want to flash a version of nina-fw Arduino IDE does not know about yet.  
    25  There is no way to "refresh" firmware versions list, but you can "fool" Arduino IDE by substituting, say, 1.4.5 binary with 1.4.8 binary.  
    26  For that you need to locate the binary Arduino IDE going to flash and replace it with a new file.  
    27  Location differs from OS to OS, on macOS it's in "/Applications/Arduino.app/Contents/Java/tools/WiFi101/tool/firmwares/NINA/".  
    28  Replace respective binary ".bin" file with new file and follow tutorial steps above flashing "1.4.5" version while in fact it is going to flash "1.4.8".
    29  
    30  Latest firmware binary file for your board can be downloaded from their [releases page](https://github.com/arduino/nina-fw/releases).
    31  
    32  Verify correct version flashed with "Examples/WiFiNINA/Tools/CheckFirmwareVersion" sketch in Arduino IDE.
    33  
    34  ### Update Arduino Boards without Arduino IDE
    35  
    36  #### Download nina-fw firmware binary
    37  
    38  ```shell
    39  # wget
    40  wget https://github.com/arduino/nina-fw/releases/download/1.4.8/NINA_W102-v1.4.8.bin
    41  # curl
    42  curl -LO https://github.com/arduino/nina-fw/releases/download/1.4.8/NINA_W102-v1.4.8.bin
    43  ```
    44  
    45  #### Install esptool to flash nina-fw firmware
    46  
    47  In order to flash the firmware, you need to use Python to install the `esptool` package.
    48  
    49  ```shell
    50  pip install esptool
    51  ```
    52  
    53  On macOS you can also use brew
    54  
    55  ```shell
    56  brew install esptool
    57  ```
    58  
    59  Once you have installed `esptool` you can follow the procedure below for flashing your board.
    60  
    61  Note: We use `esptool` executable in the rest of the document, you may find yourself using `esptool.py` instead, depends on OS and way you install it.
    62  Note: Port `/dev/ttyACM0` is valid for Linux; on macOS it shall be something like `/dev/tty.usbmodem14101`; on Windows expect to see `COM1` or alike.
    63  
    64  #### Update nina-fw on the Arduino Nano33 IoT
    65  
    66  In the `updater` directory we have a precompiled binary of the "passthrough" code you will need to flash first, in order to update the ESP32 co-processor on your board.
    67  
    68  This is what needs to be done. There is also a bash script that performs the same steps also located in the `updater` directory.
    69  
    70  ```shell
    71  
    72  # reset board into bootloader mode using 1200 baud
    73  stty -F /dev/ttyACM0 ispeed 1200 ospeed 1200
    74  
    75  # flash the passthru binary to the SAMD21 using bossac
    76  # code from https://github.com/arduino-libraries/WiFiNINA/blob/master/examples/Tools/SerialNINAPassthrough/SerialNINAPassthrough.ino
    77  bossac -d -i -e -w -v -R --port=/dev/ttyACM0 --offset=0x2000 ./SerialNINAPassthrough.ino.nano_33_iot.bin
    78  
    79  # flash the nina-fw binary to the ESP32 using esptool
    80  esptool --port /dev/ttyACM0 --before default_reset --baud 115200 write_flash 0 ./NINA_W102-v1.4.8.bin
    81  ```
    82  
    83  You only need to do this one time, and then the correct nina-fw firmware will be on the NINA ESP32 chip, and you can just flash the Arduino Nano33 IoT board using TinyGo.
    84  
    85  #### Update nina-fw on the Arduino Nano RP2040 Connect
    86  
    87  In the `updater` directory we have a precompiled binary of the "passthrough" code you will need to flash first, in order to update the ESP32 co-processor on your board.
    88  
    89  Put Nano RP2040 Connect into Mass Storage Device mode by shorting REC and GND pins while plugging it in. Alternatively you can short the pins and press button on top side of the board while keeping the board connected to your computer. Release the pins and "RPI-RP2" storage device shall appear mounted.
    90  
    91  Copy `SerialNINAPassthrough.ino.nano_rp2040_connect.uf2` file over to storage device and it must eject rebooting.
    92  
    93  Now you can use `esptool` to flash nina-fw to ESP32 chip on the board.
    94  
    95  ```shell
    96  esptool --port /dev/ttyACM0 --before no_reset --baud 115200 write_flash 0 ./NINA_W102-v1.4.8.bin
    97  ```
    98  
    99  Verify correct version of nina-fw installed by flasing `CheckFirmwareVersion.ino.uf2` on the board the same way you flashed `SerialNINAPassthrough.ino.nano_rp2040_connect.uf2` before. You must connect to the board with a serial monitor, for example Arduino IDE, alternatively `screen` or `picocom` cli commands.
   100  
   101  ### Update Adafruit ESP32 WiFi Boards
   102  
   103  Adafruit provides very good instructions for updating their boards that provide a ESP32 WiFi-BLE co-processor. For more information, please see:
   104  
   105  https://learn.adafruit.com/upgrading-esp32-firmware
   106  
   107  ## Updating the driver
   108  
   109  If you modify the WiFiNINA status or command codes, you will also need to regenerate the display strings.
   110  
   111  ```
   112  go generate ./wifinina/status.go ./wifinina/commands.go
   113  ```
   114  
   115  ## Debugging
   116  
   117  You can output debug information to the serial console by using the `wifidebug` tag.
   118  
   119  ```
   120  tinygo flash -target pyportal -ldflags="-X main.ssid=something -X main.pass=somethingelse" -tags=wifidebug -monitor ./examples/wifinina/webclient/
   121  ```