diff --git a/.gitignore b/.gitignore index 180c0d15..cd6e129a 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,7 @@ public build node_modules npm-debug.log + +# generated by "hugo serve" +resources +.hugo_build.lock diff --git a/content/docs/reference/hardware-matrix.md b/content/docs/reference/hardware-matrix.md new file mode 100644 index 00000000..bd67ba1a --- /dev/null +++ b/content/docs/reference/hardware-matrix.md @@ -0,0 +1,112 @@ +--- +title: " Supported hardware feature matrix" +weight: 10 +description: > + Matrix between Microcontrollers and Features +--- + +Notes: + +* '-': Not supported by Hardware +* '?': Supported status is currently unknown +* 'n': Not yet supported by TinyGo +* 'p': Partially supported by TinyGo +* 'x': Supported + +see TinyGo documentation of the microcontroller for details to: + +* WiFi +* BT (Bluetooth) +* IMU (Inertial measurement unit, e.g. acceleration, rotation, magnetometer) +* NePx (NeoPixel, WS2812) +* other (other peripheral or built-in devices, e.g. temperature, GSM) + +| Microcontroller |GPIO|UART|SPI|I2C|ADC|PWM|USBDev|BT |WiFi|IMU|NePx|other| +|:-------------------------------------------:|:--:|:--:|:-:|:-:|:-:|:-:|:----:|:-:|:--:|:-:|:--:|:---:| +| [Adafruit Circuit Playground Bluefruit](https://www.adafruit.com/product/4333)| x | x | x | x | x | x | x | x | - | x | x | p | +| [Adafruit Circuit Playground Express](https://www.adafruit.com/product/3333) | x | x | x | x | x | x | x | - | - | x | x | p | +| [Adafruit CLUE](https://www.adafruit.com/product/4500) | x | x | x | x | x | x | x | x | - | x | x | p | +| [Adafruit Feather M0](https://www.adafruit.com/product/3403) | x | x | x | x | x | x | x | - | - | - | - | - | +| [Adafruit Feather M4](https://www.adafruit.com/product/3857) | x | x | x | x | x | x | x | - | - | - | x | - | +| [Adafruit Feather M4 CAN](https://www.adafruit.com/product/4759) | x | x | x | x | x | x | x | - | - | - | x | - | +| [Adafruit Feather nRF52840 Express](https://www.adafruit.com/product/4062) | x | x | x | x | x | x | x | x | - | - | x | - | +| [Adafruit Feather nRF52840 Sense](https://www.adafruit.com/product/4516) | x | x | x | x | x | x | x | x | - | x | x | p | +| [Adafruit Feather RP2040](https://www.adafruit.com/product/4884) | x | x | x | x | x | x | x | - | - | - | - | - | +| [Adafruit Feather STM32F405 Express](https://www.adafruit.com/product/4382) | x | x | x | x | x | n | n | - | - | - | x | - | +| [Adafruit Grand Central M4](https://www.adafruit.com/product/4064) | x | x | x | x | x | x | x | - | - | - | x | - | +| [Adafruit ItsyBitsy M0](https://www.adafruit.com/product/3727) | x | x | x | x | x | x | x | - | - | - | - | - | +| [Adafruit ItsyBitsy M4](https://www.adafruit.com/product/3800) | x | x | x | x | x | x | x | - | - | - | - | - | +| [Adafruit ItsyBitsy nRF52840 Express](https://www.adafruit.com/product/4481) | x | x | x | x | x | x | x | x | - | - | n | - | +| [Adafruit MacroPad RP2040](https://www.adafruit.com/product/5100) | x | x | x | x | x | x | x | - | - | - | x | - | +| [Adafruit Matrix Portal M4](https://www.adafruit.com/product/4745) | x | x | x | x | x | x | x | - | n | x | x | p | +| [Adafruit Metro M4 Express AirLift](https://www.adafruit.com/product/4000) | x | x | x | x | x | x | x | - | n | - | x | - | +| [Adafruit PyBadge](https://www.adafruit.com/product/4200) | x | x | x | x | x | x | x | - | - | x | x | p | +| [Adafruit PyGamer](https://www.adafruit.com/product/4242) | x | x | x | x | x | x | x | - | - | x | x | p | +| [Adafruit PyPortal](https://www.adafruit.com/product/4116) | x | x | x | x | x | x | x | - | n | x | x | p | +| [Adafruit QT Py](https://www.adafruit.com/product/4600) | x | x | x | x | x | x | x | - | - | - | x | - | +| [Adafruit QT Py ESP32-C3](https://www.adafruit.com/product/5405) | x | x | x | x | n | n | n | n | n | - | x | - | +| [Adafruit QT Py RP2040](https://www.adafruit.com/product/4900) | x | x | x | x | x | x | x | - | - | - | x | - | +| [Adafruit Trinket M0](https://www.adafruit.com/product/3500) | x | x | x | x | x | x | x | - | - | - | - | - | +| [Adafruit Trinkey QT2040](https://www.adafruit.com/product/5056) | x | x | x | x | x | x | x | - | - | - | x | - | +| [Arduino Mega 1280](https://docs.arduino.cc/retired/other/arduino-older-boards#arduino-mega/) | x | x | x | x | x | x | - | - | - | - | - | - | +| [Arduino Mega 2560](https://store.arduino.cc/arduino-mega-2560-rev3) | x | x | x | x | x | n | - | - | - | - | - | - | +| [Arduino MKR WiFi 1010](https://store.arduino.cc/usa/mkr-wifi-1010) | x | x | x | x | x | x | x | x | x | - | - | - | +| [Arduino MKR1000](https://store.arduino.cc/arduino-mkr1000-wifi) | x | x | x | x | x | x | x | x | x | - | - | - | +| [Arduino Nano](https://store.arduino.cc/arduino-nano) | x | x | x | x | x | x | - | - | - | - | - | - | +| [Arduino Nano 33 BLE (Sense)](https://store.arduino.cc/arduino-nano-33-ble) | x | x | x | x | x | x | x | x | - | x | - | p | +| [Arduino Nano 33 IoT](https://store.arduino.cc/nano-33-iot) | x | x | x | x | x | x | x | x | x | x | - | p | +| [Arduino Nano RP2040 Connect](https://store.arduino.cc/nano-rp2040-connect) | x | x | x | x | x | x | x | x | x | x | - | p | +| [Arduino Uno](https://store.arduino.cc/arduino-uno-rev3) | x | x | x | x | x | x | - | - | - | - | - | - | +| [Arduino Zero](https://store.arduino.cc/arduino-zero) | x | x | x | x | x | x | x | - | - | - | - | - | +| [BBC micro:bit](https://microbit.org) | x | x | x | x | x | n | - | x | - | n | - | p | +| [Blues Wireless Swan](https://blues.io/products/swan/) | x | x | x | x | n | n | n | - | - | - | - | p | +| [Digispark](http://digistump.com/products/1) | x | n | n | n | x | n | - | - | - | - | - | - | +| [Dragino LoRaWAN GPS Tracker LGT-92](https://www.dragino.com/products/lora-lorawan-end-node/item/142-lgt-92.html) | x | x | x | x | n | n | n | - | - | n | - | - | +| [ESP32 - mini32](https://www.lilygo.cc/en-pl/products/t7-v1-3-mini-32-esp32) | x | x | x | n | n | n | - | n | n | - | - | - | +| [ESP32 Core Board V2](https://docs.espressif.com/projects/esp-idf/en/release-v3.0/hw-reference/modules-and-boards.html#esp32-core-board-v2-esp32-devkitc) | x | x | x | n | n | n | - | n | n | - | - | - | +| [ESP8266 - d1mini](https://botland.store/withdrawn-products/6257-d1-mini-wifi-esp8266-iot-compatible-with-wemos-and-arduino.html) | x | x | n | n | n | n | - | - | n | - | - | - | +| [ESP8266 - NodeMCU](https://en.wikipedia.org/wiki/NodeMCU) | x | x | n | n | n | n | - | - | n | - | - | - | +| [Game Boy Advance](https://en.wikipedia.org/wiki/Game_Boy_Advance) | ? | ? | ? | ? | ? | ? | ? | - | - | - | - | - | +| [iLabs Challenger RP2040 LoRa](https://ilabs.se/product/challenger-rp2040-lora/) | x | x | x | x | x | x | x | - | - | - | - | p | +| [M5Stack BASIC Kit](https://docs.m5stack.com/en/core/basic) | x | x | x | n | n | n | - | n | n | - | - | - | +| [M5Stack Core2](https://shop.m5stack.com/products/m5stack-core2-esp32-iot-development-kit) | x | x | x | n | n | n | - | n | n | - | - | - | +| [M5Stack M5Stamp-C3](https://docs.m5stack.com/en/core/stamp_c3) | x | x | x | n | n | n | n | n | n | - | x | - | +| [Makerdiary nRF52840-MDK](https://wiki.makerdiary.com/nrf52840-mdk/) | x | x | x | x | x | x | x | x | - | - | - | - | +| [Makerdiary nRF52840-MDK USB Dongle](https://wiki.makerdiary.com/nrf52840-mdk-usb-dongle/) | x | x | x | x | x | x | x | x | - | - | - | - | +| [Microchip SAM E54 Xplained Pro](https://www.microchip.com/developmenttools/productdetails/atsame54-xpro) | x | x | x | x | x | x | x | - | - | - | - | - | +| [Nice Keyboards nice!nano](https://nicekeyboards.com/products/nice-nano-v1-0) | x | x | x | x | x | x | x | x | - | - | - | - | +| [Nintendo Switch](https://en.wikipedia.org/wiki/Nintendo_Switch) | ? | ? | ? | ? | ? | ? | ? | - | - | - | - | - | +| [Nordic Semiconductor PCA10031](https://www.nordicsemi.com/eng/Products/nRF51-Dongle) | x | x | x | x | x | n | - | x | - | - | - | - | +| [Nordic Semiconductor PCA10040](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52-DK) | x | x | x | x | x | x | - | x | - | - | - | - | +| [Nordic Semiconductor PCA10056](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) | x | x | x | x | x | x | x | x | - | - | - | - | +| [Nordic Semiconductor PCA10059](https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF52840-Dongle) | x | x | x | x | x | x | x | x | - | - | - | - | +| [Particle Argon](https://docs.particle.io/datasheets/wi-fi/argon-datasheet/) | x | x | x | x | x | x | x | x | n | - | - | - | +| [Particle Boron](https://docs.particle.io/datasheets/cellular/boron-datasheet/) | x | x | x | x | x | x | x | x | - | - | - | - | +| [Particle Xenon](https://docs.particle.io/datasheets/discontinued/xenon-datasheet/) | x | x | x | x | x | x | x | x | - | - | - | - | +| [Phytec reel board](https://www.phytec.eu/product-eu/internet-of-things/reelboard/) | x | x | x | x | x | x | x | x | - | n | - | p | +| [Pimoroni Badger2040](https://shop.pimoroni.com/products/badger-2040) | x | x | x | x | x | x | x | - | - | - | - | - | +| [Pimoroni Tufty2040](https://shop.pimoroni.com/products/tufty-2040) | x | x | x | x | x | x | x | - | - | - | - | - | +| [Pine64 PineTime](https://wiki.pine64.org/index.php/PineTime) | x | x | x | x | x | x | - | x | - | - | - | - | +| [PJRC Teensy 3.6](https://www.pjrc.com/store/teensy36.html) | x | x | n | n | n | n | n | - | - | - | - | - | +| [PJRC Teensy 4.0](https://www.pjrc.com/store/teensy40.html) | x | x | x | x | x | n | n | - | - | - | - | - | +| [ProductivityOpen P1AM-100](https://facts-engineering.github.io/modules/P1AM-100/P1AM-100.html) | x | x | x | x | x | x | x | x | x | - | - | - | +| [Raspberry Pi Pico](https://www.raspberrypi.org/products/raspberry-pi-pico/) | x | x | x | x | x | x | x | - | - | - | - | - | +| [Seeed LoRa-E5 Development Kit](https://www.seeedstudio.com/LoRa-E5-Dev-Kit-p-4868.html) | x | x | x | x | n | n | - | - | - | - | - | p | +| [Seeed Seeeduino XIAO](https://www.seeedstudio.com/Seeeduino-XIAO-Arduino-Microcontroller-SAMD21-Cortex-M0+-p-4426.html) | x | x | x | x | x | x | x | - | - | - | - | - | +| [Seeed Sipeed MAix Bit](https://www.seeedstudio.com/Sipeed-MAix-BiT-for-RISC-V-AI-IoT-p-2872.html) | x | x | x | x | - | n | ? | - | - | - | - | - | +| [Seeed Wio Terminal](https://www.seeedstudio.com/Wio-Terminal-p-4509.html) | x | x | x | x | x | x | x | n | n | n | - | p | +| [Seeed XIAO BLE](https://www.seeedstudio.com/Seeed-XIAO-BLE-nRF52840-p-5201.html) | x | x | x | x | x | x | x | x | - | - | - | - | +| [Seeed XIAO ESP32 C3](https://www.seeedstudio.com/Seeed-XIAO-ESP32C3-p-5431.html) | x | x | x | x | n | n | n | n | n | - | - | - | +| [Seeed XIAO RP2040](https://www.seeedstudio.com/XIAO-RP2040-v1-0-p-5026.html) | x | x | x | x | x | x | x | - | - | - | x | - | +| [SiFive HiFive1 Rev B](https://www.sifive.com/boards/hifive1-rev-b) | x | x | x | x | - | n | ? | - | - | - | - | - | +| [Sparkfun Thing Plus RP2040](https://www.sparkfun.com/products/17745) | x | x | x | x | x | x | x | - | - | - | n | p | +| [ST Micro STM32 "Blue Pill" F103XX](https://stm32-base.org/boards/STM32F103C8T6-Blue-Pill.html) | x | x | x | x | x | n | n | - | - | - | - | - | +| [ST Micro STM32 Nucleo-144 F722ZE](https://www.st.com/en/evaluation-tools/nucleo-f722ze.html) | x | x | n | x | n | n | n | - | - | - | - | p | +| [ST Micro STM32 Nucleo-144 L552ZE](https://www.st.com/en/evaluation-tools/nucleo-l552ze-q.html) | x | x | n | x | n | n | n | - | - | - | - | p | +| [ST Micro STM32 Nucleo-32 L031K6](https://www.st.com/en/evaluation-tools/nucleo-l031k6.html) | x | x | x | x | n | n | - | - | - | - | - | p | +| [ST Micro STM32 Nucleo-32 L432KC](https://www.st.com/en/evaluation-tools/nucleo-l432kc.html) | x | x | x | x | n | n | - | - | - | - | - | p | +| [ST Micro STM32 Nucleo-64 F103RB](https://www.st.com/en/evaluation-tools/nucleo-f103rb.html) | x | x | x | x | x | n | - | - | - | - | - | - | +| [ST Micro STM32F4 Discovery](https://www.st.com/en/evaluation-tools/stm32f4discovery.html) | x | x | x | x | x | n | n | - | - | n | - | p | +| [ST Micro STM32WL Nucleo-64 WL55JC](https://www.st.com/en/evaluation-tools/nucleo-wl55jc.html) | x | x | x | x | n | n | - | - | - | - | - | p | +| [Waveshare RP2040-Zero](https://www.waveshare.com/wiki/RP2040-Zero) | x | x | x | x | x | x | x | - | - | - | x | - | +| [X9 Pro Smartwatch](../microcontrollers/x9pro.md) | ? | ? | ? | ? | ? | ? | ? | - | - | - | - | - | diff --git a/content/docs/reference/microcontrollers/arduino-mega1280.md b/content/docs/reference/microcontrollers/arduino-mega1280.md index 83482fb6..3f9dfee1 100644 --- a/content/docs/reference/microcontrollers/arduino-mega1280.md +++ b/content/docs/reference/microcontrollers/arduino-mega1280.md @@ -3,7 +3,7 @@ title: "Arduino Mega 1280" weight: 3 --- -The [Arduino Mega 1280](https://www.arduino.cc/en/Main/arduinoBoardMega/) is based on the AVR [ATmega1280](https://www.microchip.com/wwwproducts/en/ATMEGA1280) microcontroller. +The [Arduino Mega 1280](https://docs.arduino.cc/retired/other/arduino-older-boards#arduino-mega/) is based on the AVR [ATmega1280](https://www.microchip.com/wwwproducts/en/ATMEGA1280) microcontroller. Note: the AVR backend of LLVM is still experimental so you may encounter bugs. diff --git a/content/docs/reference/microcontrollers/arduino-mkr1000.md b/content/docs/reference/microcontrollers/arduino-mkr1000.md index 0d5492c9..18612364 100644 --- a/content/docs/reference/microcontrollers/arduino-mkr1000.md +++ b/content/docs/reference/microcontrollers/arduino-mkr1000.md @@ -3,7 +3,13 @@ title: "Arduino MKR1000" weight: 3 --- -The [Arduino MKR1000](https://store.arduino.cc/arduino-mkr1000-wifi) is a very small ARM development board based on the Microchip [SAMD21](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of processors. It also has a NINA-W102 chip onboard which provides an wireless communication abilities based on the popular ESP32 family of wireless chips from Espressif. +The [Arduino MKR1000](https://store.arduino.cc/arduino-mkr1000-wifi) is a very small ARM development board based on the Microchip [SAMD21](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of processors. + +## Peripherals and Drivers + +- [NINA-W102](https://github.com/tinygo-org/drivers/tree/release/wifinina) chip for WiFi, Bluetooth + +You can also use the Espressif ESP-AT firmware, although you will need to flash it yourself. Please see the [espat driver](https://github.com/tinygo-org/drivers/tree/release/espat). ## Interfaces @@ -127,7 +133,3 @@ Once you have updated your Arduino MKR1000 board the first time, after that you ## Notes You can use the USB port to the Arduino MKR1000 as a serial port. `UART0` refers to this connection. - -For information on how to use the built-in NINA-W102 wireless chip with the default firmware, please see the "wifinina" driver in the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/wifinina](https://github.com/tinygo-org/drivers/tree/release/wifinina). - -You can also use the Espressif ESP-AT firmware, although you will need to flash it yourself. Please see the "espat" driver in the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/espat](https://github.com/tinygo-org/drivers/tree/release/espat). diff --git a/content/docs/reference/microcontrollers/arduino-mkrwifi1010.md b/content/docs/reference/microcontrollers/arduino-mkrwifi1010.md index 5a11ac2c..1cb1da87 100644 --- a/content/docs/reference/microcontrollers/arduino-mkrwifi1010.md +++ b/content/docs/reference/microcontrollers/arduino-mkrwifi1010.md @@ -3,7 +3,13 @@ title: "Arduino MKR WiFi 1010" weight: 3 --- -The [Arduino MKR WiFi 1010](https://store.arduino.cc/usa/mkr-wifi-1010) is a very small ARM development board based on the Microchip [SAMD21](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of processors. It also has a NINA-W102 chip onboard which provides an wireless communication abilities based on the popular ESP32 family of wireless chips from Espressif. +The [Arduino MKR WiFi 1010](https://store.arduino.cc/usa/mkr-wifi-1010) is a very small ARM development board based on the Microchip [SAMD21](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of processors. + +## Peripherals and Drivers + +- [NINA-W102](https://github.com/tinygo-org/drivers/tree/release/wifinina) chip for WiFi, Bluetooth + +You can also use the Espressif ESP-AT firmware, although you will need to flash it yourself. Please see the [espat driver](https://github.com/tinygo-org/drivers/tree/release/espat). ## Interfaces @@ -134,7 +140,3 @@ Once you have updated your Arduino MKR WiFi 1010 board the first time, after tha ## Notes You can use the USB port to the Arduino MKR WiFi 1010 as a serial port. `UART0` refers to this connection. - -For information on how to use the built-in NINA-W102 wireless chip with the default firmware, please see the "wifinina" driver in the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/wifinina](https://github.com/tinygo-org/drivers/tree/release/wifinina). - -You can also use the Espressif ESP-AT firmware, although you will need to flash it yourself. Please see the "espat" driver in the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/espat](https://github.com/tinygo-org/drivers/tree/release/espat). diff --git a/content/docs/reference/microcontrollers/arduino-nano33.md b/content/docs/reference/microcontrollers/arduino-nano33.md index f333360b..c88e5919 100644 --- a/content/docs/reference/microcontrollers/arduino-nano33.md +++ b/content/docs/reference/microcontrollers/arduino-nano33.md @@ -3,11 +3,14 @@ title: "Arduino Nano 33 IoT" weight: 3 --- -The [Arduino Nano33 IoT](https://store.arduino.cc/nano-33-iot) is a very small ARM development board based on the Atmel [SAMD21](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of processors. It also has a NINA-W102 chip onboard which provides an wireless communication abilities based on the popular ESP32 family of wireless chips from Espressif. +The [Arduino Nano 33 IoT](https://store.arduino.cc/nano-33-iot) is a very small ARM development board based on the Atmel [SAMD21](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of processors. -Peripherals: -- NINA-W102 chip with [wifinina](https://github.com/tinygo-org/drivers/tree/release/wifinina) firmware (wifi and bluetooth) -- [lsm6ds3](https://github.com/tinygo-org/drivers/tree/release/lsm6ds3) IMU chip (acceleration, rotation and temperature) +## Peripherals and Drivers + +- [NINA-W102](https://github.com/tinygo-org/drivers/tree/release/wifinina) chip for WiFi, Bluetooth +- [LSM6DS3](https://github.com/tinygo-org/drivers/tree/release/lsm6ds3) chip for IMU (accelerometer, gyroscope), temperature + +You can also use the Espressif ESP-AT firmware, although you will need to flash it yourself. Please see the [espat driver](https://github.com/tinygo-org/drivers/tree/release/espat). ## Interfaces @@ -146,7 +149,3 @@ Once you have updated your Arduino Nano33 IoT board the first time, after that y ## Notes You can use the USB port to the Arduino Nano33 IoT as a serial port. `UART0` refers to this connection. - -For information on how to use the built-in NINA-W102 wireless chip with the default firmware, please see the "wifinina" driver in the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/wifinina](https://github.com/tinygo-org/drivers/tree/release/wifinina). - -You can also use the Espressif ESP-AT firmware, although you will need to flash it yourself. Please see the "espat" driver in the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/espat](https://github.com/tinygo-org/drivers/tree/release/espat). diff --git a/content/docs/reference/microcontrollers/arduino-zero.md b/content/docs/reference/microcontrollers/arduino-zero.md index 241bfe58..e8a53646 100644 --- a/content/docs/reference/microcontrollers/arduino-zero.md +++ b/content/docs/reference/microcontrollers/arduino-zero.md @@ -113,13 +113,12 @@ Once you have installed the needed BOSSA command line utility, as in the previou - Plug your Arduino Zero board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the Arduino Zero with the blinky1 example: - ``` + ```shell tinygo flash -target=arduino-zero examples/blinky1 ``` - The Arduino Zero board should restart and then begin running your program. - ### Troubleshooting If you have troubles getting your Arduino Zero board to receive code, try this: diff --git a/content/docs/reference/microcontrollers/atsame54-xpro.md b/content/docs/reference/microcontrollers/atsame54-xpro.md index b6089519..aebacc56 100644 --- a/content/docs/reference/microcontrollers/atsame54-xpro.md +++ b/content/docs/reference/microcontrollers/atsame54-xpro.md @@ -3,7 +3,7 @@ title: "Microchip SAM E54 Xplained Pro" weight: 3 --- -The [Microchip SAM E54 Xplained Pro](https://www.microchip.com/developmenttools/productdetails/atsame54-xpro) is a tiny ARM development board based on the Atmel [ATSAME54P20](https://www.microchip.com/wwwproducts/en/ATSAME54P20A) family of SoC. +The [SAM E54 Xplained Pro](https://www.microchip.com/developmenttools/productdetails/atsame54-xpro) is a tiny ARM development board based on the Atmel [ATSAME54P20](https://www.microchip.com/wwwproducts/en/ATSAME54P20A) family of SoC. ## Interfaces diff --git a/content/docs/reference/microcontrollers/badger2040.md b/content/docs/reference/microcontrollers/badger2040.md index b2fe9ea0..13b58451 100644 --- a/content/docs/reference/microcontrollers/badger2040.md +++ b/content/docs/reference/microcontrollers/badger2040.md @@ -3,7 +3,7 @@ title: "Pimoroni Badger2040" weight: 3 --- -The [Pimoroni Badger2040](https://shop.pimoroni.com/products/badger-2040) is a badge with E Ink display based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. +The [Badger2040](https://shop.pimoroni.com/products/badger-2040) is a badge with E Ink display based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. ## Interfaces diff --git a/content/docs/reference/microcontrollers/bluepill.md b/content/docs/reference/microcontrollers/bluepill.md index c4a8530f..66838f16 100644 --- a/content/docs/reference/microcontrollers/bluepill.md +++ b/content/docs/reference/microcontrollers/bluepill.md @@ -1,9 +1,9 @@ --- -title: 'ST Micro STM32F103XX "Bluepill"' +title: 'ST Micro STM32 "Blue Pill" F103XX' weight: 3 --- -The [Bluepill](http://wiki.stm32duino.com/index.php?title=Blue_Pill) is a popular, ultra-cheap and compact ARM development board based on the ST Micro [STM32F103C8](https://www.st.com/en/microcontrollers/stm32f103c8.html) SoC. +The ["Blue Pill"](https://stm32-base.org/boards/STM32F103C8T6-Blue-Pill.html) is a popular, ultra-cheap and compact ARM development board based on the ST Micro [STM32F103C8](https://www.st.com/en/microcontrollers/stm32f103c8.html) SoC. ## Interfaces diff --git a/content/docs/reference/microcontrollers/challenger-rp2040.md b/content/docs/reference/microcontrollers/challenger-rp2040.md index 9bf9370b..26af5766 100644 --- a/content/docs/reference/microcontrollers/challenger-rp2040.md +++ b/content/docs/reference/microcontrollers/challenger-rp2040.md @@ -3,7 +3,11 @@ title: "iLabs Challenger RP2040 LoRa" weight: 3 --- -The [iLabs Challenger RP2040 LoRa](https://ilabs.se/product/challenger-rp2040-lora/) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. +The [Challenger RP2040 LoRa](https://ilabs.se/product/challenger-rp2040-lora/) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. + +## Peripherals and Drivers + +- RFM95W LoRa via SPI ## Interfaces diff --git a/content/docs/reference/microcontrollers/circuitplay-bluefruit.md b/content/docs/reference/microcontrollers/circuitplay-bluefruit.md index 4c975038..27d29620 100644 --- a/content/docs/reference/microcontrollers/circuitplay-bluefruit.md +++ b/content/docs/reference/microcontrollers/circuitplay-bluefruit.md @@ -3,7 +3,17 @@ title: "Adafruit Circuit Playground Bluefruit" weight: 3 --- -The [Adafruit Circuit Playground Bluefruit](https://www.adafruit.com/product/4333) is small ARM development board based on the Nordic Semiconductor [nrf52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. It has several built-in devices such as WS2812 "NeoPixel" LEDs, buttons, an accelerometer, and some other sensors. +The [Circuit Playground Bluefruit](https://www.adafruit.com/product/4333) is small ARM development board based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth +- [LIS3DH](https://pkg.go.dev/tinygo.org/x/drivers/lis3dh) IMU chip (acceleration, tap detection, free-fall detection) +- MEMS microphone +- [Thermistor](https://pkg.go.dev/tinygo.org/x/drivers/thermistor) temperature sensor +- Light sensor (phototransistor) +- [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) Neopixel via the `D8` pin, [example](https://github.com/tinygo-org/drivers/tree/release/examples/ws2812) +- Buttons ## Interfaces @@ -87,19 +97,13 @@ Once you have updated your Circuit Playground Bluefruit board the first time, af You can use the USB port to the Circuit Playground Bluefruit as a serial port. `UART0` refers to this connection. -The Neopixel LED on the Circuit Playground Bluefruit can be accessed using the [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) driver via the `D8` pin. - -For an example that uses the built-in Neopixel LEDs, take a look at the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/examples](https://github.com/tinygo-org/drivers) - -Bluetooth support is now available for the Circuit Playground Bluefruit board. See https://github.com/tinygo-org/bluetooth for more information. - ## Updating the UF2 bootloader This board uses a UF2 bootloader created by Adafruit: https://github.com/adafruit/Adafruit_nRF52_Bootloader We recommend bootloader version 0.4.1 or above. You can check what version is installed on your board by double-clicking the button on the board to launch the bootloader. When you do this, a USB volume that should automatically be mounted on your computer. Check the file named "INFO_UF2.TXT" on that drive. The bootloader firmware version should be listed in that file, for example: -``` +```shell UF2 Bootloader 0.4.1 lib/nrfx (v2.0.0) lib/tinyusb (0.6.0-272-g4e6aa0d8) lib/uf2 (remotes/origin/configupdate-9-gadbb8c7) Model: Adafruit Circuit Playground nRF52840 Board-ID: nRF52840-CircuitPlayground-revD @@ -107,7 +111,7 @@ SoftDevice: S140 version 6.1.1 Date: Jan 19 2021 ``` -To update the bootloader, you will need to install the `adafruit-nrfutil` program. +To update the bootloader, you will need to install the `adafruit-nrfutil` program. You can install it by running: @@ -115,10 +119,10 @@ You can install it by running: pip3 install --user adafruit-nrfutil ``` -Once you have installed the `adafruit-nrfutil` program, download the firmware here: +Once you have installed the `adafruit-nrfutil` program, download the firmware here: https://github.com/adafruit/Adafruit_nRF52_Bootloader/releases/download/0.4.1/circuitplayground_nrf52840_bootloader-0.4.1.zip -Unzip the files in this zip file and save them to a convenient location. +Unzip the files in this zip file and save them to a convenient location. Plug in your Circuit Playground Bluefruit board to your computer's USB port. diff --git a/content/docs/reference/microcontrollers/circuitplay-express.md b/content/docs/reference/microcontrollers/circuitplay-express.md index de207152..e3b3b2f4 100644 --- a/content/docs/reference/microcontrollers/circuitplay-express.md +++ b/content/docs/reference/microcontrollers/circuitplay-express.md @@ -3,7 +3,18 @@ title: "Adafruit Circuit Playground Express" weight: 3 --- -The [Adafruit Circuit Playground Express](https://www.adafruit.com/product/3333) is small ARM development board based on the Atmel [SAMD21](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of processors. It has several built-in devices such as WS2812 "NeoPixel" LEDs, buttons, an accelerometer, and some other sensors. +The [Circuit Playground Express](https://www.adafruit.com/product/3333) is small ARM development board based on the Atmel [SAMD21](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of processors. + +## Peripherals and Drivers + +- [LIS3DH](https://pkg.go.dev/tinygo.org/x/drivers/lis3dh) IMU chip (acceleration, tap detection, free-fall detection) +- MEMS microphone +- Mini speaker +- [Thermistor](https://pkg.go.dev/tinygo.org/x/drivers/thermistor) temperature sensor +- Light sensor (phototransistor) +- [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) Neopixel via the `PB23` pin, [example](https://github.com/tinygo-org/drivers/tree/release/examples/ws2812) + +- Buttons, Slide switch ## Interfaces @@ -85,7 +96,3 @@ Once you have updated your Circuit Playground Express board the first time, afte ## Notes You can use the USB port to the Circuit Playground Express as a serial port. `UART0` refers to this connection. - -The Neopixel LED on the Circuit Playground Express can be accessed using the [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) driver via the `PB23` pin. - -For an example that uses the built-in Neopixel LEDs, take a look at the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/examples](https://github.com/tinygo-org/drivers) diff --git a/content/docs/reference/microcontrollers/clue.md b/content/docs/reference/microcontrollers/clue.md index 239a3204..9423c38b 100644 --- a/content/docs/reference/microcontrollers/clue.md +++ b/content/docs/reference/microcontrollers/clue.md @@ -3,7 +3,21 @@ title: "Adafruit CLUE" weight: 3 --- -The [Adafruit CLUE](https://www.adafruit.com/product/4500) is small ARM development board based on the Nordic Semiconductor [nrf52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. It has several built-in devices such as WS2812 "NeoPixel" LEDs, buttons, an accelerometer, and some other sensors. +The [CLUE](https://www.adafruit.com/product/4500) is small ARM development board based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth +- [LSM6DS33](https://github.com/tinygo-org/drivers/tree/release/lsm6ds3) IMU chip (acceleration, rotation) +- LIS3MDL magnetometer +- [APDS9960](https://github.com/tinygo-org/drivers/tree/release/apds9960) Proximity, Light, Color, and Gesture Sensor +- [SHT](https://github.com/tinygo-org/drivers/tree/release/sht3x) Humidity +- [BMP280](https://github.com/tinygo-org/drivers/tree/release/bmp280) temperature and barometric pressure/altitude +- PDM MEMS microphone +- Buzzer/Speaker +- [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) Neopixel via the `D18` pin, [example](https://github.com/tinygo-org/drivers/tree/release/examples/ws2812) +- Buttons +- IPS TFT display ## Interfaces @@ -103,17 +117,13 @@ Once you have updated your CLUE board the first time, after that you should be a You can use the USB port to the CLUE as a serial port. `UART0` refers to this connection. -For an example that uses the built-in Neopixel LEDs, take a look at the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/examples](https://github.com/tinygo-org/drivers) - -Bluetooth support is now available for the Adafruit CLUE board. See https://github.com/tinygo-org/bluetooth for more information. - ## Updating the UF2 bootloader This board uses a UF2 bootloader created by Adafruit: https://github.com/adafruit/Adafruit_nRF52_Bootloader We recommend bootloader version 0.4.1 or above. You can check what version is installed on your board by double-clicking the button on the board to launch the bootloader. When you do this, a USB volume that should automatically be mounted on your computer. Check the file named "INFO_UF2.TXT" on that drive. The bootloader firmware version should be listed in that file, for example: -``` +```shell UF2 Bootloader 0.4.1 lib/nrfx (v2.0.0) lib/tinyusb (0.6.0-272-g4e6aa0d8) lib/uf2 (remotes/origin/configupdate-9-gadbb8c7) Model: Adafruit CLUE nRF52840 Board-ID: nRF52840-CLUE-revA @@ -121,7 +131,7 @@ SoftDevice: S140 version 6.1.1 Date: Jan 19 2021 ``` -To update the bootloader, you will need to install the `adafruit-nrfutil` program. +To update the bootloader, you will need to install the `adafruit-nrfutil` program. You can install it by running: @@ -129,10 +139,10 @@ You can install it by running: pip3 install --user adafruit-nrfutil ``` -Once you have installed the `adafruit-nrfutil` program, download the firmware here: +Once you have installed the `adafruit-nrfutil` program, download the firmware here: https://github.com/adafruit/Adafruit_nRF52_Bootloader/releases/download/0.4.1/clue_nrf52840_bootloader-0.4.1.zip -Unzip the files in this zip file and save them to a convenient location. +Unzip the files in this zip file and save them to a convenient location. Plug in your board to your computer's USB port. diff --git a/content/docs/reference/microcontrollers/d1mini.md b/content/docs/reference/microcontrollers/d1mini.md index 0d2230b4..dffd5c08 100644 --- a/content/docs/reference/microcontrollers/d1mini.md +++ b/content/docs/reference/microcontrollers/d1mini.md @@ -3,7 +3,11 @@ title: "ESP8266 - d1mini" weight: 3 --- -The [Espressif ESP8266](https://www.espressif.com/en/products/socs/esp8266) d1mini is a very small yet powerful SoC that is usually used for WiFi applications thanks to its built-in radio. +The [d1mini](https://botland.store/withdrawn-products/6257-d1-mini-wifi-esp8266-iot-compatible-with-wemos-and-arduino.html) is a board based on the [Espressif ESP8266](https://www.espressif.com/en/products/socs/esp8266). + +## Peripherals and Drivers + +A small yet powerful SoC that is usually used for WiFi applications thanks to its built-in radio. ## Interfaces @@ -42,7 +46,7 @@ The [Espressif ESP8266](https://www.espressif.com/en/products/socs/esp8266) d1mi ### CLI Flashing on Linux -You need to install the same toolchain for the ESP8266 as is used for the ESP32 to use the ESP8266 with TinyGo: +You need to install the same toolchain for the ESP8266 as is used for the ESP32 to use the ESP8266 with TinyGo: https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/linux-setup.html#standard-setup-of-toolchain-for-linux @@ -55,7 +59,7 @@ Now you should be able to flash your board as follows: - Plug your ESP8266 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP8266 with the blinky1 example: - ``` + ```shell tinygo flash -target=d1mini -port=/dev/ttyUSB examples/blinky1 ``` @@ -76,7 +80,7 @@ Now you should be able to flash your board as follows: - Plug your ESP8266 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP8266 with the blinky1 example: - ``` + ```shell tinygo flash -target=d1mini examples/blinky1 ``` @@ -97,16 +101,8 @@ Now you should be able to flash your board as follows: - Plug your ESP826 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP826 with the blinky1 example: - ``` + ```shell tinygo flash -target=d1mini examples/blinky1 ``` - The ESP826 board should restart and then begin running your program. - -### Troubleshooting - -Goes here - -## Notes - -Goes here diff --git a/content/docs/reference/microcontrollers/digispark.md b/content/docs/reference/microcontrollers/digispark.md index f7793c54..73085833 100644 --- a/content/docs/reference/microcontrollers/digispark.md +++ b/content/docs/reference/microcontrollers/digispark.md @@ -3,7 +3,7 @@ title: "Digispark" weight: 3 --- -The [Digispark](http://digistump.com/products/1) is an [ATtiny85](https://www.microchip.com/wwwproducts/en/ATtiny85) based microcontroller development board similar to the Arduino line, only cheaper, smaller, and a bit less powerful. +The [Digispark](http://digistump.com/products/1) is an [ATtiny85](https://www.microchip.com/wwwproducts/en/ATtiny85) based microcontroller development board similar to the Arduino line, only cheaper, smaller, and a bit less powerful. There is very limited support at the moment for this board. diff --git a/content/docs/reference/microcontrollers/esp32-coreboard-v2.md b/content/docs/reference/microcontrollers/esp32-coreboard-v2.md index a0b4c739..fda34311 100644 --- a/content/docs/reference/microcontrollers/esp32-coreboard-v2.md +++ b/content/docs/reference/microcontrollers/esp32-coreboard-v2.md @@ -1,9 +1,13 @@ --- -title: "ESP32 - Core board" +title: "ESP32 Core Board V2" weight: 3 --- -The esp32-coreboard-v2 is a development board based on the [Espressif ESP32](https://www.espressif.com/en/products/socs/esp32) a powerful chip that is used on many different board mostly because of the built-in radio that can be used for WiFi or Bluetooth wireless connections. +The [ESP32 Core Board V2](https://docs.espressif.com/projects/esp-idf/en/release-v3.0/hw-reference/modules-and-boards.html#esp32-core-board-v2-esp32-devkitc) is a development board based on the [Espressif ESP32](https://www.espressif.com/en/products/socs/esp32). + +## Peripherals and Drivers + +A powerful chip that is used on many different boards mostly because of the built-in radio that can be used for WiFi or Bluetooth wireless connections. ## Interfaces @@ -73,7 +77,7 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the blinky1 example: - ``` + ```shell tinygo flash -target=esp32-coreboard-v2 -port=/dev/ttyUSB0 examples/blinky1 ``` @@ -90,7 +94,7 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the blinky1 example: - ``` + ```shell tinygo flash -target=esp32-coreboard-v2 examples/blinky1 ``` @@ -107,16 +111,8 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the blinky1 example: - ``` + ```shell tinygo flash -target=esp32-coreboard-v2 examples/blinky1 ``` - The ESP32 board should restart and then begin running your program. - -### Troubleshooting - -Goes here - -## Notes - -Goes here diff --git a/content/docs/reference/microcontrollers/esp32-mini32.md b/content/docs/reference/microcontrollers/esp32-mini32.md index debba0bf..76e03a44 100644 --- a/content/docs/reference/microcontrollers/esp32-mini32.md +++ b/content/docs/reference/microcontrollers/esp32-mini32.md @@ -3,7 +3,11 @@ title: "ESP32 - mini32" weight: 3 --- -The mini32 is a small development board based on the popular [Espressif ESP32](https://www.espressif.com/en/products/socs/esp32). The ESP32 includes a built-in radio that can be used for WiFi or Bluetooth wireless connections. +The [ESP32 - mini32](https://www.lilygo.cc/en-pl/products/t7-v1-3-mini-32-esp32) is a small development board based on the popular [Espressif ESP32](https://www.espressif.com/en/products/socs/esp32). + +## Peripherals and Drivers + +The ESP32 includes a built-in radio that can be used for WiFi or Bluetooth wireless connections. ## Interfaces @@ -73,7 +77,7 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the blinky1 example: - ``` + ```shell tinygo flash -target=esp32-mini32 -port=/dev/ttyUSB0 examples/blinky1 ``` @@ -90,7 +94,7 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the blinky1 example: - ``` + ```shell tinygo flash -target=esp32-mini32 examples/blinky1 ``` @@ -107,16 +111,8 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the blinky1 example: - ``` + ```shell tinygo flash -target=esp32-mini32 examples/blinky1 ``` - The ESP32 board should restart and then begin running your program. - -### Troubleshooting - -Goes here - -## Notes - -Goes here diff --git a/content/docs/reference/microcontrollers/feather-m0.md b/content/docs/reference/microcontrollers/feather-m0.md index 092a5f09..ef1a3639 100644 --- a/content/docs/reference/microcontrollers/feather-m0.md +++ b/content/docs/reference/microcontrollers/feather-m0.md @@ -3,7 +3,7 @@ title: "Adafruit Feather M0" weight: 3 --- -The [Adafruit Feather M0](https://www.adafruit.com/product/3403) is a tiny ARM development board based on the Atmel [ATSAMD21G18](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of SoC. +The [Feather M0](https://www.adafruit.com/product/3403) is a tiny ARM development board based on the Atmel [ATSAMD21G18](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of SoC. ## Interfaces @@ -76,10 +76,9 @@ If you have troubles getting your Feather M0 board to receive code, try this: - The Feather M0 board will appear to your computer like a USB drive. - Now try running the command as above: - -```shell -tinygo flash -target=feather-m0 [PATH TO YOUR PROGRAM] -``` + ```shell + tinygo flash -target=feather-m0 [PATH TO YOUR PROGRAM] + ``` Once you have updated your Feather M0 board the first time, after that you should be able to flash it entirely from the command line. diff --git a/content/docs/reference/microcontrollers/feather-m4-can.md b/content/docs/reference/microcontrollers/feather-m4-can.md index b4bb7f9e..6cc6c13c 100644 --- a/content/docs/reference/microcontrollers/feather-m4-can.md +++ b/content/docs/reference/microcontrollers/feather-m4-can.md @@ -3,7 +3,7 @@ title: "Adafruit Feather M4 CAN" weight: 3 --- -The [Adafruit Feather M4 CAN](https://www.adafruit.com/product/4759) is a tiny ARM development board based on the Atmel [ATSAME51J19](https://www.microchip.com/wwwproducts/en/ATSAME51J19A) family of SoC. +The [Feather M4 CAN](https://www.adafruit.com/product/4759) is a tiny ARM development board based on the Atmel [ATSAME51J19](https://www.microchip.com/wwwproducts/en/ATSAME51J19A) family of SoC. ## Interfaces @@ -78,7 +78,6 @@ The Feather M4 CAN comes with the [UF2 bootloader](https://github.com/Microsoft/ - The Feather M4 CAN board should restart and then begin running your program. - ### Troubleshooting If you have troubles getting your Feather M4 CAN board to receive code, try this: @@ -87,10 +86,9 @@ If you have troubles getting your Feather M4 CAN board to receive code, try this - The Feather M4 CAN board will appear to your computer like a USB drive. - Now try running the command as above: - -```shell -tinygo flash -target=feather-m4-can [PATH TO YOUR PROGRAM] -``` + ```shell + tinygo flash -target=feather-m4-can [PATH TO YOUR PROGRAM] + ``` Once you have updated your Feather M4 CAN board the first time, after that you should be able to flash it entirely from the command line. diff --git a/content/docs/reference/microcontrollers/feather-m4.md b/content/docs/reference/microcontrollers/feather-m4.md index 2d9c88c3..d5c94aa5 100644 --- a/content/docs/reference/microcontrollers/feather-m4.md +++ b/content/docs/reference/microcontrollers/feather-m4.md @@ -3,7 +3,7 @@ title: "Adafruit Feather M4" weight: 3 --- -The [Adafruit Feather M4](https://www.adafruit.com/product/3857) is a tiny ARM development board based on the Atmel [ATSAMD51J19](https://www.microchip.com/wwwproducts/en/ATSAMD51J19A) family of SoC. +The [Feather M4](https://www.adafruit.com/product/3857) is a tiny ARM development board based on the Atmel [ATSAMD51J19](https://www.microchip.com/wwwproducts/en/ATSAMD51J19A) family of SoC. ## Interfaces @@ -73,7 +73,6 @@ The Feather M4 comes with the [UF2 bootloader](https://github.com/Microsoft/uf2) - The Feather M4 board should restart and then begin running your program. - ### Troubleshooting If you have troubles getting your Feather M4 board to receive code, try this: @@ -82,10 +81,9 @@ If you have troubles getting your Feather M4 board to receive code, try this: - The Feather M4 board will appear to your computer like a USB drive. - Now try running the command as above: - -```shell -tinygo flash -target=feather-m4 [PATH TO YOUR PROGRAM] -``` + ```shell + tinygo flash -target=feather-m4 [PATH TO YOUR PROGRAM] + ``` Once you have updated your Feather M4 board the first time, after that you should be able to flash it entirely from the command line. diff --git a/content/docs/reference/microcontrollers/feather-nrf52840-sense.md b/content/docs/reference/microcontrollers/feather-nrf52840-sense.md index 67c6c308..5c569917 100644 --- a/content/docs/reference/microcontrollers/feather-nrf52840-sense.md +++ b/content/docs/reference/microcontrollers/feather-nrf52840-sense.md @@ -3,7 +3,18 @@ title: "Adafruit Feather nRF52840 Sense" weight: 3 --- -The [Adafruit Feather nRF52840 Sense](https://www.adafruit.com/product/4516) is a small ARM development board based on the Nordic Semiconductor [nrf52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. +The [Feather nRF52840 Sense](https://www.adafruit.com/product/4516) is a small ARM development board based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth +- [LSM6DS33](https://github.com/tinygo-org/drivers/tree/release/lsm6ds3) IMU chip (acceleration, rotation) +- LIS3MDL magnetometer +- [APDS9960](https://github.com/tinygo-org/drivers/tree/release/apds9960) Proximity, Light, Color, and Gesture Sensor +- PDM Microphone sound sensor +- [SHT](https://github.com/tinygo-org/drivers/tree/release/sht3x) Humidity +- [BMP280](https://github.com/tinygo-org/drivers/tree/release/bmp280) temperature and barometric pressure/altitude sensor +- [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) Neopixel (built-in) ## Interfaces @@ -98,15 +109,13 @@ Once you have updated your Adafruit Feather nRF52840 Sense board the first time, You can use the USB port to the Adafruit Feather nRF52840 Sense as a serial port. `UART0` refers to this connection. -Bluetooth support is now available for the Adafruit Feather nRF52840 Sense board. See https://github.com/tinygo-org/bluetooth for more information. - ## Updating the UF2 bootloader This board uses a UF2 bootloader created by Adafruit: https://github.com/adafruit/Adafruit_nRF52_Bootloader We recommend bootloader version 0.4.1 or above. You can check what version is installed on your board by double-clicking the button on the board to launch the bootloader. When you do this, a USB volume that should automatically be mounted on your computer. Check the file named "INFO_UF2.TXT" on that drive. The bootloader firmware version should be listed in that file, for example: -``` +```shell UF2 Bootloader 0.4.1 lib/nrfx (v2.0.0) lib/tinyusb (0.6.0-272-g4e6aa0d8) lib/uf2 (remotes/origin/configupdate-9-gadbb8c7) Model: Adafruit CLUE nRF52840 Board-ID: nRF52840-CLUE-revA @@ -114,7 +123,7 @@ SoftDevice: S140 version 6.1.1 Date: Jan 19 2021 ``` -To update the bootloader, you will need to install the `adafruit-nrfutil` program. +To update the bootloader, you will need to install the `adafruit-nrfutil` program. You can install it by running: @@ -122,10 +131,10 @@ You can install it by running: pip3 install --user adafruit-nrfutil ``` -Once you have installed the `adafruit-nrfutil` program, download the firmware here: +Once you have installed the `adafruit-nrfutil` program, download the firmware here: https://github.com/adafruit/Adafruit_nRF52_Bootloader/releases/download/0.4.1/feather_nrf52840_sense_bootloader-0.4.1.zip -Unzip the files in this zip file and save them to a convenient location. +Unzip the files in this zip file and save them to a convenient location. Plug in your board to your computer's USB port. diff --git a/content/docs/reference/microcontrollers/feather-nrf52840.md b/content/docs/reference/microcontrollers/feather-nrf52840.md index 3ff61ba7..38e3884b 100644 --- a/content/docs/reference/microcontrollers/feather-nrf52840.md +++ b/content/docs/reference/microcontrollers/feather-nrf52840.md @@ -3,7 +3,11 @@ title: "Adafruit Feather nRF52840 Express" weight: 3 --- -The [Adafruit Feather nRF52840](https://www.adafruit.com/product/4500) is a small ARM development board based on the Nordic Semiconductor [nrf52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. +The [Feather nRF52840 Express](https://www.adafruit.com/product/4062) is a small ARM development board based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth ## Interfaces @@ -98,15 +102,13 @@ Once you have updated your Adafruit Feather nRF52840 board the first time, after You can use the USB port to the Adafruit Feather nRF52840 as a serial port. `UART0` refers to this connection. -Bluetooth support is now available for the Adafruit Feather nRF52840 board. See https://github.com/tinygo-org/bluetooth for more information. - ## Updating the UF2 bootloader This board uses a UF2 bootloader created by Adafruit: https://github.com/adafruit/Adafruit_nRF52_Bootloader We recommend bootloader version 0.4.1 or above. You can check what version is installed on your board by double-clicking the button on the board to launch the bootloader. When you do this, a USB volume that should automatically be mounted on your computer. Check the file named "INFO_UF2.TXT" on that drive. The bootloader firmware version should be listed in that file, for example: -``` +```shell UF2 Bootloader 0.4.1 lib/nrfx (v2.0.0) lib/tinyusb (0.6.0-272-g4e6aa0d8) lib/uf2 (remotes/origin/configupdate-9-gadbb8c7) Model: Adafruit CLUE nRF52840 Board-ID: nRF52840-CLUE-revA @@ -114,7 +116,7 @@ SoftDevice: S140 version 6.1.1 Date: Jan 19 2021 ``` -To update the bootloader, you will need to install the `adafruit-nrfutil` program. +To update the bootloader, you will need to install the `adafruit-nrfutil` program. You can install it by running: @@ -122,10 +124,10 @@ You can install it by running: pip3 install --user adafruit-nrfutil ``` -Once you have installed the `adafruit-nrfutil` program, download the firmware here: +Once you have installed the `adafruit-nrfutil` program, download the firmware here: https://github.com/adafruit/Adafruit_nRF52_Bootloader/releases/download/0.4.1/feather_nrf52840_express_bootloader-0.4.1.zip -Unzip the files in this zip file and save them to a convenient location. +Unzip the files in this zip file and save them to a convenient location. Plug in your board to your computer's USB port. diff --git a/content/docs/reference/microcontrollers/feather-rp2040.md b/content/docs/reference/microcontrollers/feather-rp2040.md index b9f227af..a7b68956 100644 --- a/content/docs/reference/microcontrollers/feather-rp2040.md +++ b/content/docs/reference/microcontrollers/feather-rp2040.md @@ -3,7 +3,7 @@ title: "Adafruit Feather RP2040" weight: 3 --- -The [Adafruit Feather RP2040](https://www.adafruit.com/product/4884) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. +The [Feather RP2040](https://www.adafruit.com/product/4884) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. ## Interfaces diff --git a/content/docs/reference/microcontrollers/feather-stm32f405.md b/content/docs/reference/microcontrollers/feather-stm32f405.md index d63dd726..cb87c3f8 100644 --- a/content/docs/reference/microcontrollers/feather-stm32f405.md +++ b/content/docs/reference/microcontrollers/feather-stm32f405.md @@ -3,7 +3,7 @@ title: "Adafruit Feather STM32F405 Express" weight: 3 --- -The [Adafruit Feather STM32F405](https://www.adafruit.com/product/4382) is a tiny ARM development board based on the ST Micro [STM32F405](https://www.st.com/resource/en/datasheet/dm00037051.pdf) family of microcontrollers. +The [Feather STM32F405 Express](https://www.adafruit.com/product/4382) is a tiny ARM development board based on the ST Micro [STM32F405](https://www.st.com/resource/en/datasheet/dm00037051.pdf) family of microcontrollers. ## Interfaces @@ -89,14 +89,10 @@ You must first install the `dfu-util` program in order to flash the Adafruit Fea You must first install the `dfu-util` program in order to flash the Adafruit Feather STM32F405 board. -- Download dfu-util from the website here: http://dfu-util.sourceforge.net/releases/dfu-util-0.9-win64.zip +- Download dfu-util from the website here: https://dfu-util.sourceforge.net/releases/dfu-util-0.9-win64.zip - Decompress the files to a directory such as `C:\dfu-util` - Add `C:\dfu-util` to your `PATH`. ### Troubleshooting If you run into trouble getting dfu-util installed and working on Windows, see the blog post at https://www.hanselman.com/blog/HowToFixDfuutilSTMWinUSBZadigBootloadersAndOtherFirmwareFlashingIssuesOnWindows.aspx - -## Notes - -Goes here diff --git a/content/docs/reference/microcontrollers/gameboy-advance.md b/content/docs/reference/microcontrollers/gameboy-advance.md index 7f816d9c..7f8ff88a 100644 --- a/content/docs/reference/microcontrollers/gameboy-advance.md +++ b/content/docs/reference/microcontrollers/gameboy-advance.md @@ -23,8 +23,7 @@ The [Game Boy Advance](https://en.wikipedia.org/wiki/Game_Boy_Advance) is a hand ## Installing dependencies -You can use a Game Boy Advance software emulator such as MGBA (https://mgba.io) to test your programs. - +You can use a Game Boy Advance software emulator such as [MGBA](https://mgba.io) to test your programs. ## Building code diff --git a/content/docs/reference/microcontrollers/grandcentral-m4.md b/content/docs/reference/microcontrollers/grandcentral-m4.md index 5d301ddb..5c0c2028 100644 --- a/content/docs/reference/microcontrollers/grandcentral-m4.md +++ b/content/docs/reference/microcontrollers/grandcentral-m4.md @@ -3,7 +3,11 @@ title: "Adafruit Grand Central M4" weight: 3 --- -The [Adafruit Grand Central M4](https://www.adafruit.com/product/4064) is a tiny ARM development board based on the Atmel [ATSAMD51P20](https://www.microchip.com/wwwproducts/en/ATSAMD51P20A) family of SoC. +The [Grand Central M4](https://www.adafruit.com/product/4064) is a tiny ARM development board based on the Atmel [ATSAMD51P20](https://www.microchip.com/wwwproducts/en/ATSAMD51P20A) family of SoC. + +## Peripherals and Drivers + +- [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) Neopixel via the `PC24` pin ## Interfaces @@ -132,7 +136,6 @@ The Grand Central M4 comes with the [UF2 bootloader](https://github.com/Microsof - The Grand Central M4 board should restart and then begin running your program. - ### Troubleshooting If you have troubles getting your Grand Central M4 board to receive code, try this: @@ -141,15 +144,12 @@ If you have troubles getting your Grand Central M4 board to receive code, try th - The Grand Central M4 board will appear to your computer like a USB drive. - Now try running the command as above: - -```shell -tinygo flash -target=grandcentral-m4 [PATH TO YOUR PROGRAM] -``` + ```shell + tinygo flash -target=grandcentral-m4 [PATH TO YOUR PROGRAM] + ``` Once you have updated your Grand Central M4 board the first time, after that you should be able to flash it entirely from the command line. ## Notes You can use the USB port to the Grand Central M4 as a serial port. `UART0` refers to this connection. - -The Neopixel LED on the Grand Central M4 can be accessed using the [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) driver via the `PC24` pin diff --git a/content/docs/reference/microcontrollers/itsybitsy-m0.md b/content/docs/reference/microcontrollers/itsybitsy-m0.md index 1fe6c959..c43c282a 100644 --- a/content/docs/reference/microcontrollers/itsybitsy-m0.md +++ b/content/docs/reference/microcontrollers/itsybitsy-m0.md @@ -3,7 +3,11 @@ title: "Adafruit ItsyBitsy M0" weight: 3 --- -The [Adafruit ItsyBitsy M0](https://www.adafruit.com/product/3727) is very compact ARM development board based on the Atmel [SAMD21](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of SoC. +The [ItsyBitsy M0](https://www.adafruit.com/product/3727) is very compact ARM development board based on the Atmel [SAMD21](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of SoC. + +## Peripherals and Drivers + +The DotStar LED on the ItsyBitsy M0 can be accessed using the [APA102](https://pkg.go.dev/tinygo.org/x/drivers/apa102) driver via a software SPI on the `PA00` and `PA01` pins. ## Interfaces @@ -91,5 +95,3 @@ Once you have updated your ItsyBitsy M0 board the first time, after that you sho ## Notes You can use the USB port to the ItsyBitsy M0 as a serial port. `UART0` refers to this connection. - -The DotStar LED on the ItsyBitsy M0 can be accessed using the [APA102](https://pkg.go.dev/tinygo.org/x/drivers/apa102) driver via a software SPI on the `PA00` and `PA01` pins diff --git a/content/docs/reference/microcontrollers/itsybitsy-m4.md b/content/docs/reference/microcontrollers/itsybitsy-m4.md index e56e4fa5..5effd042 100644 --- a/content/docs/reference/microcontrollers/itsybitsy-m4.md +++ b/content/docs/reference/microcontrollers/itsybitsy-m4.md @@ -3,7 +3,11 @@ title: "Adafruit ItsyBitsy M4" weight: 3 --- -The [Adafruit ItsyBitsy M4](https://www.adafruit.com/product/3800) is very compact ARM development board based on the Atmel [SAMD51](https://www.microchip.com/wwwproducts/en/ATSAMD51G19A) family of SoC. +The [ItsyBitsy M4](https://www.adafruit.com/product/3800) is very compact ARM development board based on the Atmel [SAMD51](https://www.microchip.com/wwwproducts/en/ATSAMD51G19A) family of SoC. + +## Peripherals and Drivers + +The DotStar LED on the ItsyBitsy M4 can be accessed using the [APA102](https://pkg.go.dev/tinygo.org/x/drivers/apa102) driver via a software SPI on the `PB02` and `PB03` pins. ## Interfaces @@ -93,5 +97,3 @@ Once you have updated your ItsyBitsy M4 board the first time, after that you sho ## Notes You can use the USB port to the ItsyBitsy M4 as a serial port. `UART0` refers to this connection. - -The DotStar LED on the ItsyBitsy M4 can be accessed using the [APA102](https://pkg.go.dev/tinygo.org/x/drivers/apa102) driver via a software SPI on the `PB02` and `PB03` pins diff --git a/content/docs/reference/microcontrollers/itsybitsy-nrf52840.md b/content/docs/reference/microcontrollers/itsybitsy-nrf52840.md index 4e1cd094..00354b60 100644 --- a/content/docs/reference/microcontrollers/itsybitsy-nrf52840.md +++ b/content/docs/reference/microcontrollers/itsybitsy-nrf52840.md @@ -1,9 +1,15 @@ --- -title: "Adafruit ItsyBitsy nRF52840" +title: "Adafruit ItsyBitsy nRF52840 Express" weight: 3 --- -The [Adafruit ItsyBitsy-nRF52840](https://www.adafruit.com/product/4333) is a small ARM development board based on the Nordic Semiconductor [nrf52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. +The [ItsyBitsy nRF52840 Express](https://www.adafruit.com/product/4481) is a small ARM development board based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth + +For an example that uses the built-in Neopixel LEDs, take a look at the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/examples](https://github.com/tinygo-org/drivers) ## Interfaces @@ -95,17 +101,13 @@ Once you have updated your ItsyBitsy-nRF52840 board the first time, after that y You can use the USB port to the ItsyBitsy-nRF52840 as a serial port. `UART0` refers to this connection. -For an example that uses the built-in Neopixel LEDs, take a look at the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/examples](https://github.com/tinygo-org/drivers) - -Bluetooth support is now available for the ItsyBitsy-nRF52840 board. See https://github.com/tinygo-org/bluetooth for more information. - ## Updating the UF2 bootloader This board uses a UF2 bootloader created by Adafruit: https://github.com/adafruit/Adafruit_nRF52_Bootloader We recommend bootloader version 0.4.1 or above. You can check what version is installed on your board by double-clicking the button on the board to launch the bootloader. When you do this, a USB volume that should automatically be mounted on your computer. Check the file named "INFO_UF2.TXT" on that drive. The bootloader firmware version should be listed in that file, for example: -``` +```shell UF2 Bootloader 0.4.1 lib/nrfx (v2.0.0) lib/tinyusb (0.6.0-272-g4e6aa0d8) lib/uf2 (remotes/origin/configupdate-9-gadbb8c7) Model: Adafruit ItsyBitsy nRF52840 Express Board-ID: nRF52840-ItsyBitsy-revA @@ -113,7 +115,7 @@ SoftDevice: S140 version 6.1.1 Date: Jan 19 2021 ``` -To update the bootloader, you will need to install the `adafruit-nrfutil` program. +To update the bootloader, you will need to install the `adafruit-nrfutil` program. You can install it by running: @@ -121,10 +123,10 @@ You can install it by running: pip3 install --user adafruit-nrfutil ``` -Once you have installed the `adafruit-nrfutil` program, download the firmware here: +Once you have installed the `adafruit-nrfutil` program, download the firmware here: https://github.com/adafruit/Adafruit_nRF52_Bootloader/releases/download/0.4.1/itsybitsy_nrf52840_express_bootloader-0.4.1.zip -Unzip the files in this zip file and save them to a convenient location. +Unzip the files in this zip file and save them to a convenient location. Plug in your board to your computer's USB port. diff --git a/content/docs/reference/microcontrollers/lgt92.md b/content/docs/reference/microcontrollers/lgt92.md index e6f7b583..b0e309e6 100644 --- a/content/docs/reference/microcontrollers/lgt92.md +++ b/content/docs/reference/microcontrollers/lgt92.md @@ -3,7 +3,12 @@ title: "Dragino LoRaWAN GPS Tracker LGT-92" weight: 3 --- -The [Dragino LGT-92](https://www.dragino.com/products/lora-lorawan-end-node/item/142-lgt-92.html) includes a low power GPS module L76-L and 9-axis accelerometer for motion and attitude detection. It is based on the ST Micro [STM32L072CZT6](https://www.st.com/en/microcontrollers-microprocessors/stm32l072cz.html) SoC. +The [LoRaWAN GPS Tracker LGT-92](https://www.dragino.com/products/lora-lorawan-end-node/item/142-lgt-92.html) is based on the ST Micro [STM32L072CZT6](https://www.st.com/en/microcontrollers-microprocessors/stm32l072cz.html) SoC. + +## Peripherals and Drivers + +- low power GPS module L76-L +- 9-axis accelerometer for motion and attitude detection ## Interfaces diff --git a/content/docs/reference/microcontrollers/lorae5.md b/content/docs/reference/microcontrollers/lorae5.md index e4796f06..9546151b 100644 --- a/content/docs/reference/microcontrollers/lorae5.md +++ b/content/docs/reference/microcontrollers/lorae5.md @@ -1,11 +1,16 @@ --- -title: "Seeed Studio LoRa-E5 Development Kit" +title: "Seeed LoRa-E5 Development Kit" weight: 3 --- The [LoRa-E5 Development Kit](https://www.seeedstudio.com/LoRa-E5-Dev-Kit-p-4868.html) is an ARM development board based on the ST Micro [STM32WLE5JC](https://www.st.com/en/microcontrollers-microprocessors/stm32wle5jc.html) SoC. -It has onboard LoRa®, (G)FSK, (G)MSK, and BPSK as well as 1 user LED, 1 user buttons and 1 reset push-button +## Peripherals and Drivers + +- LoRa®, (G)FSK, (G)MSK, and BPSK. +- Button +- LED +- Temperature sensor ## Interfaces diff --git a/content/docs/reference/microcontrollers/m5stack-core2.md b/content/docs/reference/microcontrollers/m5stack-core2.md index c98f36c4..8804a737 100644 --- a/content/docs/reference/microcontrollers/m5stack-core2.md +++ b/content/docs/reference/microcontrollers/m5stack-core2.md @@ -3,7 +3,11 @@ title: "M5Stack Core2" weight: 3 --- -The [m5stack-core2](https://shop.m5stack.com/products/m5stack-core2-esp32-iot-development-kit) is a development board based on the Espressif ESP32 a powerful chip that is used on many different board mostly because of the built-in radio that can be used for WiFi or Bluetooth wireless connections. +The [Core2](https://shop.m5stack.com/products/m5stack-core2-esp32-iot-development-kit) is a development board based on the [Espressif ESP32](https://www.espressif.com/en/products/socs/esp32). + +## Peripherals and Drivers + +A powerful chip that is used on many different boards mostly because of the built-in radio that can be used for WiFi or Bluetooth wireless connections. ## Interfaces @@ -57,44 +61,6 @@ The [m5stack-core2](https://shop.m5stack.com/products/m5stack-core2-esp32-iot-de | `IO38` | `GPIO38` | `SPI0_SDI_PIN`, `LCD_SDI_PIN`, `SDCARD_SDI_PIN` | | `IO39` | `GPIO39` | | -## Pins - -| Pin | Hardware pin | Alternative names | -| ---------------- | ------------ | ----------------- | -| `IO0` | `GPIO0` | | -| `IO1` | `GPIO1` | `UART0_TX_PIN`, `UART_TX_PIN` | -| `IO2` | `GPIO2` | | -| `IO3` | `GPIO3` | `UART0_RX_PIN`, `UART_RX_PIN` | -| `IO4` | `GPIO4` | `SDCARD_SS_PIN` | -| `IO5` | `GPIO5` | `SPI0_CS0_PIN`, `LCD_SS_PIN` | -| `IO6` | `GPIO6` | | -| `IO7` | `GPIO7` | | -| `IO8` | `GPIO8` | | -| `IO9` | `GPIO9` | | -| `IO10` | `GPIO10` | | -| `IO11` | `GPIO11` | | -| `IO12` | `GPIO12` | | -| `IO13` | `GPIO13` | `UART1_RX_PIN` | -| `IO14` | `GPIO14` | `UART1_TX_PIN` | -| `IO15` | `GPIO15` | `LCD_DC_PIN` | -| `IO16` | `GPIO16` | | -| `IO17` | `GPIO17` | | -| `IO18` | `GPIO18` | `SPI0_SCK_PIN`, `LCD_SCK_PIN`, `SDCARD_SCK_PIN` | -| `IO19` | `GPIO19` | | -| `IO21` | `GPIO21` | `SDA0_PIN` | -| `IO22` | `GPIO22` | `SCL0_PIN` | -| `IO23` | `GPIO23` | `SPI0_SDO_PIN`, `LCD_SDO_PIN`, `SDCARD_SDO_PIN` | -| `IO25` | `GPIO25` | `DAC1` | -| `IO26` | `GPIO26` | `DAC2` | -| `IO27` | `GPIO27` | | -| `IO32` | `GPIO32` | `SDA1_PIN`, `SDA_PIN` | -| `IO33` | `GPIO33` | `SCL1_PIN`, `SCL_PIN` | -| `IO34` | `GPIO34` | | -| `IO35` | `GPIO35` | `ADC1` | -| `IO36` | `GPIO36` | `ADC2` | -| `IO38` | `GPIO38` | `SPI0_SDI_PIN`, `LCD_SDI_PIN`, `SDCARD_SDI_PIN` | -| `IO39` | `GPIO39` | | - ## Machine Package Docs [Documentation for the machine package for the M5Stack Core2](../machine/m5stack-core2) @@ -112,7 +78,7 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the serial example: - ``` + ```shell tinygo flash -target=m5stack-core2 -port=/dev/ttyUSB0 examples/serial ``` @@ -129,7 +95,7 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the serial example: - ``` + ```shell tinygo flash -target=m5stack-core2 examples/serial ``` @@ -146,16 +112,8 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the serial example: - ``` + ```shell tinygo flash -target=m5stack-core2 examples/serial ``` - The ESP32 board should restart and then begin running your program. - -### Troubleshooting - -Goes here - -## Notes - -Goes here diff --git a/content/docs/reference/microcontrollers/m5stack.md b/content/docs/reference/microcontrollers/m5stack.md index b9783d1d..75ff3d4a 100644 --- a/content/docs/reference/microcontrollers/m5stack.md +++ b/content/docs/reference/microcontrollers/m5stack.md @@ -1,9 +1,13 @@ --- -title: "M5Stack" +title: "M5Stack BASIC Kit" weight: 3 --- -The [m5stack](https://docs.m5stack.com/en/core/basic) is a development board based on the Espressif ESP32 a powerful chip that is used on many different board mostly because of the built-in radio that can be used for WiFi or Bluetooth wireless connections. +The [BASIC Kit](https://docs.m5stack.com/en/core/basic) is a development board based on the [Espressif ESP32](https://www.espressif.com/en/products/socs/esp32). + +## Peripherals and Drivers + +A powerful chip that is used on many different boards mostly because of the built-in radio that can be used for WiFi or Bluetooth wireless connections. ## Interfaces @@ -75,7 +79,7 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the serial example: - ``` + ```shell tinygo flash -target=m5stack -port=/dev/ttyUSB0 examples/serial ``` @@ -92,7 +96,7 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the serial example: - ``` + ```shell tinygo flash -target=m5stack examples/serial ``` @@ -109,16 +113,8 @@ Now you should be able to flash your board as follows: - Plug your ESP32 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32 with the serial example: - ``` + ```shell tinygo flash -target=m5stack examples/serial ``` - The ESP32 board should restart and then begin running your program. - -### Troubleshooting - -Goes here - -## Notes - -Goes here diff --git a/content/docs/reference/microcontrollers/m5stamp-c3.md b/content/docs/reference/microcontrollers/m5stamp-c3.md index 58dbf108..9e0979e6 100644 --- a/content/docs/reference/microcontrollers/m5stamp-c3.md +++ b/content/docs/reference/microcontrollers/m5stamp-c3.md @@ -1,9 +1,13 @@ --- -title: "M5Stamp C3" +title: "M5Stack M5Stamp-C3" weight: 3 --- -The [M5Stamp-C3](https://docs.m5stack.com/en/core/stamp_c3) is a development board based on the Espressif ESP32-C3 a powerful chip that is used on many different board mostly because of the built-in radio that can be used for WiFi or Bluetooth wireless connections. +The [M5Stamp-C3](https://docs.m5stack.com/en/core/stamp_c3) is a development board based on the [Espressif ESP32-C3](https://www.espressif.com/en/products/socs/esp32-c3). + +## Peripherals and Drivers + +A powerful chip that is used on many different boards mostly because of the built-in radio that can be used for WiFi or Bluetooth wireless connections. ## Interfaces @@ -63,16 +67,8 @@ Now you should be able to flash your board as follows: - Plug your ESP32-C3 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32-C3 with the serial example: - ``` + ```shell tinygo flash -target=m5stack-core2 examples/serial ``` - The ESP32-C3 board should restart and then begin running your program. - -### Troubleshooting - -Goes here - -## Notes - -Goes here diff --git a/content/docs/reference/microcontrollers/machine/nintendoswitch.md b/content/docs/reference/microcontrollers/machine/nintendoswitch.md new file mode 100644 index 00000000..386b6cd9 --- /dev/null +++ b/content/docs/reference/microcontrollers/machine/nintendoswitch.md @@ -0,0 +1,655 @@ + +--- +title: nintendoswitch +--- + + +## Constants + +```go +const Device = deviceName +``` + +Device is the running program's chip name, such as "ATSAMD51J19A" or +"nrf52840". It is not the same as the CPU name. + +The constant is some hardcoded default value if the program does not target a +particular chip but instead runs in WebAssembly for example. + + +```go +const ( + KHz = 1000 + MHz = 1000_000 + GHz = 1000_000_000 +) +``` + +Generic constants. + + +```go +const NoPin = Pin(0xff) +``` + +NoPin explicitly indicates "not a pin". Use this pin if you want to leave one +of the pins in a peripheral unconfigured (if supported by the hardware). + + +```go +const ( + PinInput PinMode = iota + PinOutput + PinInputPullup + PinInputPulldown +) +``` + + + +```go +const ( + Mode0 = 0 + Mode1 = 1 + Mode2 = 2 + Mode3 = 3 +) +``` + +SPI phase and polarity configs CPOL and CPHA + + + + + +## Variables + +```go +var ( + ErrTimeoutRNG = errors.New("machine: RNG Timeout") + ErrClockRNG = errors.New("machine: RNG Clock Error") + ErrSeedRNG = errors.New("machine: RNG Seed Error") + ErrInvalidInputPin = errors.New("machine: invalid input pin") + ErrInvalidOutputPin = errors.New("machine: invalid output pin") + ErrInvalidClockPin = errors.New("machine: invalid clock pin") + ErrInvalidDataPin = errors.New("machine: invalid data pin") + ErrNoPinChangeChannel = errors.New("machine: no channel available for pin interrupt") +) +``` + + + +```go +var ( + UART0 = &UART{0} + USB = &UART{100} +) +``` + + + +```go +var Serial = UART0 +``` + +The Serial port always points to the default UART in a simulated environment. + +TODO: perhaps this should be a special serial object that outputs via WASI +stdout calls. + + +```go +var ( + SPI0 = SPI{0} + I2C0 = &I2C{0} +) +``` + + + +```go +var ( + ErrPWMPeriodTooLong = errors.New("pwm: period too long") +) +``` + + + +```go +var ( + ErrTxInvalidSliceSize = errors.New("SPI write and read slices must be same size") + errSPIInvalidMachineConfig = errors.New("SPI port was not configured properly by the machine") +) +``` + + + + + + +### func InitADC + +```go +func InitADC() +``` + +InitADC enables support for ADC peripherals. + + +### func NewRingBuffer + +```go +func NewRingBuffer() *RingBuffer +``` + +NewRingBuffer returns a new ring buffer. + + + + +## type ADC + +```go +type ADC struct { + Pin Pin +} +``` + + + + +### func (ADC) Configure + +```go +func (adc ADC) Configure(ADCConfig) +``` + +Configure configures an ADC pin to be able to be used to read data. + + +### func (ADC) Get + +```go +func (adc ADC) Get() uint16 +``` + +Get reads the current analog value from this ADC peripheral. + + + + +## type ADCConfig + +```go +type ADCConfig struct { + Reference uint32 // analog reference voltage (AREF) in millivolts + Resolution uint32 // number of bits for a single conversion (e.g., 8, 10, 12) + Samples uint32 // number of samples for a single conversion (e.g., 4, 8, 16, 32) + SampleTime uint32 // sample time, in microseconds (µs) +} +``` + +ADCConfig holds ADC configuration parameters. If left unspecified, the zero +value of each parameter will use the peripheral's default settings. + + + + + +## type I2C + +```go +type I2C struct { + Bus uint8 +} +``` + +I2C is a generic implementation of the Inter-IC communication protocol. + + + +### func (*I2C) Configure + +```go +func (i2c *I2C) Configure(config I2CConfig) error +``` + +Configure is intended to setup the I2C interface. + + +### func (*I2C) SetBaudRate + +```go +func (i2c *I2C) SetBaudRate(br uint32) error +``` + +SetBaudRate sets the I2C frequency. + + +### func (*I2C) Tx + +```go +func (i2c *I2C) Tx(addr uint16, w, r []byte) error +``` + +Tx does a single I2C transaction at the specified address. + + + + +## type I2CConfig + +```go +type I2CConfig struct { + Frequency uint32 + SCL Pin + SDA Pin +} +``` + +I2CConfig is used to store config info for I2C. + + + + + +## type NullSerial + +```go +type NullSerial struct { +} +``` + +NullSerial is a serial version of /dev/null (or null router): it drops +everything that is written to it. + + + +### func (NullSerial) Buffered + +```go +func (ns NullSerial) Buffered() int +``` + +Buffered returns how many bytes are buffered in the UART. It always returns 0 +as there are no bytes to read. + + +### func (NullSerial) Configure + +```go +func (ns NullSerial) Configure(config UARTConfig) error +``` + +Configure does nothing: the null serial has no configuration. + + +### func (NullSerial) ReadByte + +```go +func (ns NullSerial) ReadByte() (byte, error) +``` + +ReadByte always returns an error because there aren't any bytes to read. + + +### func (NullSerial) Write + +```go +func (ns NullSerial) Write(p []byte) (n int, err error) +``` + +Write is a no-op: none of the data is being written and it will not return an +error. + + +### func (NullSerial) WriteByte + +```go +func (ns NullSerial) WriteByte(b byte) error +``` + +WriteByte is a no-op: the null serial doesn't write bytes. + + + + +## type PDMConfig + +```go +type PDMConfig struct { + Stereo bool + DIN Pin + CLK Pin +} +``` + + + + + + +## type PWMConfig + +```go +type PWMConfig struct { + // PWM period in nanosecond. Leaving this zero will pick a reasonable period + // value for use with LEDs. + // If you want to configure a frequency instead of a period, you can use the + // following formula to calculate a period from a frequency: + // + // period = 1e9 / frequency + // + Period uint64 +} +``` + +PWMConfig allows setting some configuration while configuring a PWM +peripheral. A zero PWMConfig is ready to use for simple applications such as +dimming LEDs. + + + + + +## type Pin + +```go +type Pin uint8 +``` + +Pin is a single pin on a chip, which may be connected to other hardware +devices. It can either be used directly as GPIO pin or it can be used in +other peripherals like ADC, I2C, etc. + + + +### func (Pin) Configure + +```go +func (p Pin) Configure(config PinConfig) +``` + + + +### func (Pin) Get + +```go +func (p Pin) Get() bool +``` + + + +### func (Pin) High + +```go +func (p Pin) High() +``` + +High sets this GPIO pin to high, assuming it has been configured as an output +pin. It is hardware dependent (and often undefined) what happens if you set a +pin to high that is not configured as an output pin. + + +### func (Pin) Low + +```go +func (p Pin) Low() +``` + +Low sets this GPIO pin to low, assuming it has been configured as an output +pin. It is hardware dependent (and often undefined) what happens if you set a +pin to low that is not configured as an output pin. + + +### func (Pin) Set + +```go +func (p Pin) Set(value bool) +``` + + + + + +## type PinConfig + +```go +type PinConfig struct { + Mode PinMode +} +``` + + + + + + +## type PinMode + +```go +type PinMode uint8 +``` + +PinMode sets the direction and pull mode of the pin. For example, PinOutput +sets the pin as an output and PinInputPullup sets the pin as an input with a +pull-up. + + + + + +## type RingBuffer + +```go +type RingBuffer struct { + rxbuffer [bufferSize]volatile.Register8 + head volatile.Register8 + tail volatile.Register8 +} +``` + +RingBuffer is ring buffer implementation inspired by post at +https://www.embeddedrelated.com/showthread/comp.arch.embedded/77084-1.php + + + +### func (*RingBuffer) Clear + +```go +func (rb *RingBuffer) Clear() +``` + +Clear resets the head and tail pointer to zero. + + +### func (*RingBuffer) Get + +```go +func (rb *RingBuffer) Get() (byte, bool) +``` + +Get returns a byte from the buffer. If the buffer is empty, +the method will return a false as the second value. + + +### func (*RingBuffer) Put + +```go +func (rb *RingBuffer) Put(val byte) bool +``` + +Put stores a byte in the buffer. If the buffer is already +full, the method will return false. + + +### func (*RingBuffer) Used + +```go +func (rb *RingBuffer) Used() uint8 +``` + +Used returns how many bytes in buffer have been used. + + + + +## type SPI + +```go +type SPI struct { + Bus uint8 +} +``` + + + + +### func (SPI) Configure + +```go +func (spi SPI) Configure(config SPIConfig) error +``` + + + +### func (SPI) Transfer + +```go +func (spi SPI) Transfer(w byte) (byte, error) +``` + +Transfer writes/reads a single byte using the SPI interface. + + +### func (SPI) Tx + +```go +func (spi SPI) Tx(w, r []byte) error +``` + +Tx handles read/write operation for SPI interface. Since SPI is a syncronous write/read +interface, there must always be the same number of bytes written as bytes read. +The Tx method knows about this, and offers a few different ways of calling it. + +This form sends the bytes in tx buffer, putting the resulting bytes read into the rx buffer. +Note that the tx and rx buffers must be the same size: + + spi.Tx(tx, rx) + +This form sends the tx buffer, ignoring the result. Useful for sending "commands" that return zeros +until all the bytes in the command packet have been received: + + spi.Tx(tx, nil) + +This form sends zeros, putting the result into the rx buffer. Good for reading a "result packet": + + spi.Tx(nil, rx) + + + + +## type SPIConfig + +```go +type SPIConfig struct { + Frequency uint32 + SCK Pin + SDO Pin + SDI Pin + Mode uint8 +} +``` + + + + + + +## type UART + +```go +type UART struct { + Bus uint8 +} +``` + + + + +### func (*UART) Buffered + +```go +func (uart *UART) Buffered() int +``` + +Buffered returns the number of bytes currently stored in the RX buffer. + + +### func (*UART) Configure + +```go +func (uart *UART) Configure(config UARTConfig) +``` + +Configure the UART. + + +### func (*UART) Read + +```go +func (uart *UART) Read(data []byte) (n int, err error) +``` + +Read from the UART. + + +### func (*UART) ReadByte + +```go +func (uart *UART) ReadByte() (byte, error) +``` + +ReadByte reads a single byte from the UART. + + +### func (*UART) Write + +```go +func (uart *UART) Write(data []byte) (n int, err error) +``` + +Write to the UART. + + +### func (*UART) WriteByte + +```go +func (uart *UART) WriteByte(b byte) error +``` + +WriteByte writes a single byte to the UART. + + + + +## type UARTConfig + +```go +type UARTConfig struct { + BaudRate uint32 + TX Pin + RX Pin + RTS Pin + CTS Pin +} +``` + +UARTConfig is a struct with which a UART (or similar object) can be +configured. The baud rate is usually respected, but TX and RX may be ignored +depending on the chip and the type of object. + + + + + diff --git a/content/docs/reference/microcontrollers/machine/pinetime.md b/content/docs/reference/microcontrollers/machine/pinetime.md new file mode 100644 index 00000000..947bd00a --- /dev/null +++ b/content/docs/reference/microcontrollers/machine/pinetime.md @@ -0,0 +1,1243 @@ + +--- +title: pinetime +--- + + +## Constants + +```go +const HasLowFrequencyCrystal = true +``` + +The PineTime has a low-frequency (32kHz) crystal oscillator on board. + + +```go +const ( + LED1 = LCD_BACKLIGHT_HIGH + LED2 = LCD_BACKLIGHT_MID + LED3 = LCD_BACKLIGHT_LOW + LED = LED1 +) +``` + +LEDs simply expose the three brightness level LEDs on the PineTime. They can +be useful for simple "hello world" style programs. + + +```go +const ( + UART_TX_PIN Pin = NoPin + UART_RX_PIN Pin = NoPin +) +``` + +The PineTime doesn't have a UART output. +Additionally, leaving the UART on results in a pretty big current drain. + + +```go +const ( + SPI0_SCK_PIN Pin = 2 + SPI0_SDO_PIN Pin = 3 + SPI0_SDI_PIN Pin = 4 +) +``` + +SPI pins for the PineTime. + + +```go +const ( + SDA_PIN Pin = 6 + SCL_PIN Pin = 7 +) +``` + +I2C pins for the PineTime. + + +```go +const ( + BUTTON_IN Pin = 13 + BUTTON_OUT Pin = 15 +) +``` + +Button pins. For some reason, there are two pins for the button. + + +```go +const VIBRATOR_PIN Pin = 16 +``` + +Pin for the vibrator. + + +```go +const ( + LCD_SCK = SPI0_SCK_PIN + LCD_SDI = SPI0_SDO_PIN + LCD_RS Pin = 18 + LCD_CS Pin = 25 + LCD_RESET Pin = 26 + LCD_BACKLIGHT_LOW Pin = 14 + LCD_BACKLIGHT_MID Pin = 22 + LCD_BACKLIGHT_HIGH Pin = 23 +) +``` + +LCD pins, using the naming convention of the official docs: +http://files.pine64.org/doc/PineTime/PineTime%20Port%20Assignment%20rev1.0.pdf + + +```go +const ( + TWI_FREQ_100KHZ = 100000 + TWI_FREQ_400KHZ = 400000 +) +``` + +TWI_FREQ is the I2C bus speed. Normally either 100 kHz, or 400 kHz for high-speed bus. + +Deprecated: use 100 * machine.KHz or 400 * machine.KHz instead. + + +```go +const ( + // I2CReceive indicates target has received a message from the controller. + I2CReceive I2CTargetEvent = iota + + // I2CRequest indicates the controller is expecting a message from the target. + I2CRequest + + // I2CFinish indicates the controller has ended the transaction. + // + // I2C controllers can chain multiple receive/request messages without + // relinquishing the bus by doing 'restarts'. I2CFinish indicates the + // bus has been relinquished by an I2C 'stop'. + I2CFinish +) +``` + + + +```go +const ( + // I2CModeController represents an I2C peripheral in controller mode. + I2CModeController I2CMode = iota + + // I2CModeTarget represents an I2C peripheral in target mode. + I2CModeTarget +) +``` + + + +```go +const Device = deviceName +``` + +Device is the running program's chip name, such as "ATSAMD51J19A" or +"nrf52840". It is not the same as the CPU name. + +The constant is some hardcoded default value if the program does not target a +particular chip but instead runs in WebAssembly for example. + + +```go +const ( + KHz = 1000 + MHz = 1000_000 + GHz = 1000_000_000 +) +``` + +Generic constants. + + +```go +const NoPin = Pin(0xff) +``` + +NoPin explicitly indicates "not a pin". Use this pin if you want to leave one +of the pins in a peripheral unconfigured (if supported by the hardware). + + +```go +const ( + PinInput PinMode = (nrf.GPIO_PIN_CNF_DIR_Input << nrf.GPIO_PIN_CNF_DIR_Pos) | (nrf.GPIO_PIN_CNF_INPUT_Connect << nrf.GPIO_PIN_CNF_INPUT_Pos) + PinInputPullup PinMode = PinInput | (nrf.GPIO_PIN_CNF_PULL_Pullup << nrf.GPIO_PIN_CNF_PULL_Pos) + PinInputPulldown PinMode = PinInput | (nrf.GPIO_PIN_CNF_PULL_Pulldown << nrf.GPIO_PIN_CNF_PULL_Pos) + PinOutput PinMode = (nrf.GPIO_PIN_CNF_DIR_Output << nrf.GPIO_PIN_CNF_DIR_Pos) | (nrf.GPIO_PIN_CNF_INPUT_Connect << nrf.GPIO_PIN_CNF_INPUT_Pos) +) +``` + + + +```go +const ( + PinRising PinChange = nrf.GPIOTE_CONFIG_POLARITY_LoToHi + PinFalling PinChange = nrf.GPIOTE_CONFIG_POLARITY_HiToLo + PinToggle PinChange = nrf.GPIOTE_CONFIG_POLARITY_Toggle +) +``` + +Pin change interrupt constants for SetInterrupt. + + +```go +const ( + P0_00 Pin = 0 + P0_01 Pin = 1 + P0_02 Pin = 2 + P0_03 Pin = 3 + P0_04 Pin = 4 + P0_05 Pin = 5 + P0_06 Pin = 6 + P0_07 Pin = 7 + P0_08 Pin = 8 + P0_09 Pin = 9 + P0_10 Pin = 10 + P0_11 Pin = 11 + P0_12 Pin = 12 + P0_13 Pin = 13 + P0_14 Pin = 14 + P0_15 Pin = 15 + P0_16 Pin = 16 + P0_17 Pin = 17 + P0_18 Pin = 18 + P0_19 Pin = 19 + P0_20 Pin = 20 + P0_21 Pin = 21 + P0_22 Pin = 22 + P0_23 Pin = 23 + P0_24 Pin = 24 + P0_25 Pin = 25 + P0_26 Pin = 26 + P0_27 Pin = 27 + P0_28 Pin = 28 + P0_29 Pin = 29 + P0_30 Pin = 30 + P0_31 Pin = 31 +) +``` + +Hardware pins + + +```go +const ( + Mode0 = 0 + Mode1 = 1 + Mode2 = 2 + Mode3 = 3 +) +``` + +SPI phase and polarity configs CPOL and CPHA + + +```go +const ( + // ParityNone means to not use any parity checking. This is + // the most common setting. + ParityNone UARTParity = iota + + // ParityEven means to expect that the total number of 1 bits sent + // should be an even number. + ParityEven + + // ParityOdd means to expect that the total number of 1 bits sent + // should be an odd number. + ParityOdd +) +``` + + + + + + +## Variables + +```go +var ( + ErrTimeoutRNG = errors.New("machine: RNG Timeout") + ErrClockRNG = errors.New("machine: RNG Clock Error") + ErrSeedRNG = errors.New("machine: RNG Seed Error") + ErrInvalidInputPin = errors.New("machine: invalid input pin") + ErrInvalidOutputPin = errors.New("machine: invalid output pin") + ErrInvalidClockPin = errors.New("machine: invalid clock pin") + ErrInvalidDataPin = errors.New("machine: invalid data pin") + ErrNoPinChangeChannel = errors.New("machine: no channel available for pin interrupt") +) +``` + + + +```go +var ( + // UART0 is the hardware UART on the NRF SoC. + _UART0 = UART{Buffer: NewRingBuffer()} + UART0 = &_UART0 +) +``` + +UART + + +```go +var Flash flashBlockDevice +``` + + + +```go +var ( + PWM0 = &PWM{PWM: nrf.PWM0} + PWM1 = &PWM{PWM: nrf.PWM1} + PWM2 = &PWM{PWM: nrf.PWM2} +) +``` + +PWM + + +```go +var ( + SPI0 = SPI{Bus: nrf.SPIM0, buf: new([1]byte)} + SPI1 = SPI{Bus: nrf.SPIM1, buf: new([1]byte)} + SPI2 = SPI{Bus: nrf.SPIM2, buf: new([1]byte)} +) +``` + +There are 3 SPI interfaces on the NRF528xx. + + +```go +var ( + I2C0 = &I2C{Bus: nrf.TWI0} + I2C1 = &I2C{Bus: nrf.TWI1} +) +``` + +There are 2 I2C interfaces on the NRF. + + +```go +var ( + ErrPWMPeriodTooLong = errors.New("pwm: period too long") +) +``` + + + +```go +var Serial = NullSerial{} +``` + +Serial is a null device: writes to it are ignored. + + +```go +var ( + ErrTxInvalidSliceSize = errors.New("SPI write and read slices must be same size") + errSPIInvalidMachineConfig = errors.New("SPI port was not configured properly by the machine") +) +``` + + + + + + +### func CPUFrequency + +```go +func CPUFrequency() uint32 +``` + + + +### func CPUReset + +```go +func CPUReset() +``` + +CPUReset performs a hard system reset. + + +### func DeviceID + +```go +func DeviceID() []byte +``` + +DeviceID returns an identifier that is unique within +a particular chipset. + +The identity is one burnt into the MCU itself, or the +flash chip at time of manufacture. + +It's possible that two different vendors may allocate +the same DeviceID, so callers should take this into +account if needing to generate a globally unique id. + +The length of the hardware ID is vendor-specific, but +8 bytes (64 bits) is common. + + +### func FlashDataEnd + +```go +func FlashDataEnd() uintptr +``` + +Return the end of the writable flash area. Usually this is the address one +past the end of the on-chip flash. + + +### func FlashDataStart + +```go +func FlashDataStart() uintptr +``` + +Return the start of the writable flash area, aligned on a page boundary. This +is usually just after the program and static data. + + +### func GetRNG + +```go +func GetRNG() (ret uint32, err error) +``` + +GetRNG returns 32 bits of non-deterministic random data based on internal thermal noise. +According to Nordic's documentation, the random output is suitable for cryptographic purposes. + + +### func InitADC + +```go +func InitADC() +``` + +InitADC initializes the registers needed for ADC. + + +### func InitSerial + +```go +func InitSerial() +``` + + + +### func NewRingBuffer + +```go +func NewRingBuffer() *RingBuffer +``` + +NewRingBuffer returns a new ring buffer. + + +### func ReadTemperature + +```go +func ReadTemperature() int32 +``` + +ReadTemperature reads the silicon die temperature of the chip. The return +value is in milli-celsius. + + + + +## type ADC + +```go +type ADC struct { + Pin Pin +} +``` + + + + +### func (ADC) Configure + +```go +func (a ADC) Configure(config ADCConfig) +``` + +Configure configures an ADC pin to be able to read analog data. + + +### func (ADC) Get + +```go +func (a ADC) Get() uint16 +``` + +Get returns the current value of a ADC pin in the range 0..0xffff. + + + + +## type ADCConfig + +```go +type ADCConfig struct { + Reference uint32 // analog reference voltage (AREF) in millivolts + Resolution uint32 // number of bits for a single conversion (e.g., 8, 10, 12) + Samples uint32 // number of samples for a single conversion (e.g., 4, 8, 16, 32) + SampleTime uint32 // sample time, in microseconds (µs) +} +``` + +ADCConfig holds ADC configuration parameters. If left unspecified, the zero +value of each parameter will use the peripheral's default settings. + + + + + +## type BlockDevice + +```go +type BlockDevice interface { + // ReadAt reads the given number of bytes from the block device. + io.ReaderAt + + // WriteAt writes the given number of bytes to the block device. + io.WriterAt + + // Size returns the number of bytes in this block device. + Size() int64 + + // WriteBlockSize returns the block size in which data can be written to + // memory. It can be used by a client to optimize writes, non-aligned writes + // should always work correctly. + WriteBlockSize() int64 + + // EraseBlockSize returns the smallest erasable area on this particular chip + // in bytes. This is used for the block size in EraseBlocks. + // It must be a power of two, and may be as small as 1. A typical size is 4096. + EraseBlockSize() int64 + + // EraseBlocks erases the given number of blocks. An implementation may + // transparently coalesce ranges of blocks into larger bundles if the chip + // supports this. The start and len parameters are in block numbers, use + // EraseBlockSize to map addresses to blocks. + EraseBlocks(start, len int64) error +} +``` + +BlockDevice is the raw device that is meant to store flash data. + + + + + +## type I2C + +```go +type I2C struct { + Bus *nrf.TWI_Type + mode I2CMode +} +``` + +I2C on the NRF51 and NRF52. + + + +### func (*I2C) Configure + +```go +func (i2c *I2C) Configure(config I2CConfig) error +``` + +Configure is intended to setup the I2C interface. + + +### func (*I2C) ReadRegister + +```go +func (i2c *I2C) ReadRegister(address uint8, register uint8, data []byte) error +``` + +ReadRegister transmits the register, restarts the connection as a read +operation, and reads the response. + +Many I2C-compatible devices are organized in terms of registers. This method +is a shortcut to easily read such registers. Also, it only works for devices +with 7-bit addresses, which is the vast majority. + + +### func (*I2C) SetBaudRate + +```go +func (i2c *I2C) SetBaudRate(br uint32) error +``` + +SetBaudRate sets the I2C frequency. It has the side effect of also +enabling the I2C hardware if disabled beforehand. + + +### func (*I2C) Tx + +```go +func (i2c *I2C) Tx(addr uint16, w, r []byte) (err error) +``` + +Tx does a single I2C transaction at the specified address. +It clocks out the given address, writes the bytes in w, reads back len(r) +bytes and stores them in r, and generates a stop condition on the bus. + + +### func (*I2C) WriteRegister + +```go +func (i2c *I2C) WriteRegister(address uint8, register uint8, data []byte) error +``` + +WriteRegister transmits first the register and then the data to the +peripheral device. + +Many I2C-compatible devices are organized in terms of registers. This method +is a shortcut to easily write to such registers. Also, it only works for +devices with 7-bit addresses, which is the vast majority. + + + + +## type I2CConfig + +```go +type I2CConfig struct { + Frequency uint32 + SCL Pin + SDA Pin + Mode I2CMode +} +``` + +I2CConfig is used to store config info for I2C. + + + + + +## type I2CMode + +```go +type I2CMode int +``` + +I2CMode determines if an I2C peripheral is in Controller or Target mode. + + + + + +## type I2CTargetEvent + +```go +type I2CTargetEvent uint8 +``` + +I2CTargetEvent reflects events on the I2C bus + + + + + +## type NullSerial + +```go +type NullSerial struct { +} +``` + +NullSerial is a serial version of /dev/null (or null router): it drops +everything that is written to it. + + + +### func (NullSerial) Buffered + +```go +func (ns NullSerial) Buffered() int +``` + +Buffered returns how many bytes are buffered in the UART. It always returns 0 +as there are no bytes to read. + + +### func (NullSerial) Configure + +```go +func (ns NullSerial) Configure(config UARTConfig) error +``` + +Configure does nothing: the null serial has no configuration. + + +### func (NullSerial) ReadByte + +```go +func (ns NullSerial) ReadByte() (byte, error) +``` + +ReadByte always returns an error because there aren't any bytes to read. + + +### func (NullSerial) Write + +```go +func (ns NullSerial) Write(p []byte) (n int, err error) +``` + +Write is a no-op: none of the data is being written and it will not return an +error. + + +### func (NullSerial) WriteByte + +```go +func (ns NullSerial) WriteByte(b byte) error +``` + +WriteByte is a no-op: the null serial doesn't write bytes. + + + + +## type PDMConfig + +```go +type PDMConfig struct { + Stereo bool + DIN Pin + CLK Pin +} +``` + + + + + + +## type PWM + +```go +type PWM struct { + PWM *nrf.PWM_Type + + channelValues [4]volatile.Register16 +} +``` + +PWM is one PWM peripheral, which consists of a counter and multiple output +channels (that can be connected to actual pins). You can set the frequency +using SetPeriod, but only for all the channels in this PWM peripheral at +once. + + + +### func (*PWM) Channel + +```go +func (pwm *PWM) Channel(pin Pin) (uint8, error) +``` + +Channel returns a PWM channel for the given pin. + + +### func (*PWM) Configure + +```go +func (pwm *PWM) Configure(config PWMConfig) error +``` + +Configure enables and configures this PWM. +On the nRF52 series, the maximum period is around 0.26s. + + +### func (*PWM) Set + +```go +func (pwm *PWM) Set(channel uint8, value uint32) +``` + +Set updates the channel value. This is used to control the channel duty +cycle. For example, to set it to a 25% duty cycle, use: + + ch.Set(ch.Top() / 4) + +ch.Set(0) will set the output to low and ch.Set(ch.Top()) will set the output +to high, assuming the output isn't inverted. + + +### func (*PWM) SetInverting + +```go +func (pwm *PWM) SetInverting(channel uint8, inverting bool) +``` + +SetInverting sets whether to invert the output of this channel. +Without inverting, a 25% duty cycle would mean the output is high for 25% of +the time and low for the rest. Inverting flips the output as if a NOT gate +was placed at the output, meaning that the output would be 25% low and 75% +high with a duty cycle of 25%. + + +### func (*PWM) SetPeriod + +```go +func (pwm *PWM) SetPeriod(period uint64) error +``` + +SetPeriod updates the period of this PWM peripheral. +To set a particular frequency, use the following formula: + + period = 1e9 / frequency + +If you use a period of 0, a period that works well for LEDs will be picked. + +SetPeriod will not change the prescaler, but also won't change the current +value in any of the channels. This means that you may need to update the +value for the particular channel. + +Note that you cannot pick any arbitrary period after the PWM peripheral has +been configured. If you want to switch between frequencies, pick the lowest +frequency (longest period) once when calling Configure and adjust the +frequency here as needed. + + +### func (*PWM) Top + +```go +func (pwm *PWM) Top() uint32 +``` + +Top returns the current counter top, for use in duty cycle calculation. It +will only change with a call to Configure or SetPeriod, otherwise it is +constant. + +The value returned here is hardware dependent. In general, it's best to treat +it as an opaque value that can be divided by some number and passed to +pwm.Set (see pwm.Set for more information). + + + + +## type PWMConfig + +```go +type PWMConfig struct { + // PWM period in nanosecond. Leaving this zero will pick a reasonable period + // value for use with LEDs. + // If you want to configure a frequency instead of a period, you can use the + // following formula to calculate a period from a frequency: + // + // period = 1e9 / frequency + // + Period uint64 +} +``` + +PWMConfig allows setting some configuration while configuring a PWM +peripheral. A zero PWMConfig is ready to use for simple applications such as +dimming LEDs. + + + + + +## type Pin + +```go +type Pin uint8 +``` + +Pin is a single pin on a chip, which may be connected to other hardware +devices. It can either be used directly as GPIO pin or it can be used in +other peripherals like ADC, I2C, etc. + + + +### func (Pin) Configure + +```go +func (p Pin) Configure(config PinConfig) +``` + +Configure this pin with the given configuration. + + +### func (Pin) Get + +```go +func (p Pin) Get() bool +``` + +Get returns the current value of a GPIO pin when the pin is configured as an +input or as an output. + + +### func (Pin) High + +```go +func (p Pin) High() +``` + +High sets this GPIO pin to high, assuming it has been configured as an output +pin. It is hardware dependent (and often undefined) what happens if you set a +pin to high that is not configured as an output pin. + + +### func (Pin) Low + +```go +func (p Pin) Low() +``` + +Low sets this GPIO pin to low, assuming it has been configured as an output +pin. It is hardware dependent (and often undefined) what happens if you set a +pin to low that is not configured as an output pin. + + +### func (Pin) PortMaskClear + +```go +func (p Pin) PortMaskClear() (*uint32, uint32) +``` + +Return the register and mask to disable a given port. This can be used to +implement bit-banged drivers. + + +### func (Pin) PortMaskSet + +```go +func (p Pin) PortMaskSet() (*uint32, uint32) +``` + +Return the register and mask to enable a given GPIO pin. This can be used to +implement bit-banged drivers. + + +### func (Pin) Set + +```go +func (p Pin) Set(high bool) +``` + +Set the pin to high or low. +Warning: only use this on an output pin! + + +### func (Pin) SetInterrupt + +```go +func (p Pin) SetInterrupt(change PinChange, callback func(Pin)) error +``` + +SetInterrupt sets an interrupt to be executed when a particular pin changes +state. The pin should already be configured as an input, including a pull up +or down if no external pull is provided. + +This call will replace a previously set callback on this pin. You can pass a +nil func to unset the pin change interrupt. If you do so, the change +parameter is ignored and can be set to any value (such as 0). + + + + +## type PinChange + +```go +type PinChange uint8 +``` + + + + + + +## type PinConfig + +```go +type PinConfig struct { + Mode PinMode +} +``` + + + + + + +## type PinMode + +```go +type PinMode uint8 +``` + +PinMode sets the direction and pull mode of the pin. For example, PinOutput +sets the pin as an output and PinInputPullup sets the pin as an input with a +pull-up. + + + + + +## type RingBuffer + +```go +type RingBuffer struct { + rxbuffer [bufferSize]volatile.Register8 + head volatile.Register8 + tail volatile.Register8 +} +``` + +RingBuffer is ring buffer implementation inspired by post at +https://www.embeddedrelated.com/showthread/comp.arch.embedded/77084-1.php + + + +### func (*RingBuffer) Clear + +```go +func (rb *RingBuffer) Clear() +``` + +Clear resets the head and tail pointer to zero. + + +### func (*RingBuffer) Get + +```go +func (rb *RingBuffer) Get() (byte, bool) +``` + +Get returns a byte from the buffer. If the buffer is empty, +the method will return a false as the second value. + + +### func (*RingBuffer) Put + +```go +func (rb *RingBuffer) Put(val byte) bool +``` + +Put stores a byte in the buffer. If the buffer is already +full, the method will return false. + + +### func (*RingBuffer) Used + +```go +func (rb *RingBuffer) Used() uint8 +``` + +Used returns how many bytes in buffer have been used. + + + + +## type SPI + +```go +type SPI struct { + Bus *nrf.SPIM_Type + buf *[1]byte // 1-byte buffer for the Transfer method +} +``` + +SPI on the NRF. + + + +### func (SPI) Configure + +```go +func (spi SPI) Configure(config SPIConfig) error +``` + +Configure is intended to setup the SPI interface. + + +### func (SPI) Transfer + +```go +func (spi SPI) Transfer(w byte) (byte, error) +``` + +Transfer writes/reads a single byte using the SPI interface. + + +### func (SPI) Tx + +```go +func (spi SPI) Tx(w, r []byte) error +``` + +Tx handles read/write operation for SPI interface. Since SPI is a syncronous +write/read interface, there must always be the same number of bytes written +as bytes read. Therefore, if the number of bytes don't match it will be +padded until they fit: if len(w) > len(r) the extra bytes received will be +dropped and if len(w) < len(r) extra 0 bytes will be sent. + + + + +## type SPIConfig + +```go +type SPIConfig struct { + Frequency uint32 + SCK Pin + SDO Pin + SDI Pin + LSBFirst bool + Mode uint8 +} +``` + +SPIConfig is used to store config info for SPI. + + + + + +## type UART + +```go +type UART struct { + Buffer *RingBuffer +} +``` + +UART on the NRF. + + + +### func (*UART) Buffered + +```go +func (uart *UART) Buffered() int +``` + +Buffered returns the number of bytes currently stored in the RX buffer. + + +### func (*UART) Configure + +```go +func (uart *UART) Configure(config UARTConfig) +``` + +Configure the UART. + + +### func (*UART) Read + +```go +func (uart *UART) Read(data []byte) (n int, err error) +``` + +Read from the RX buffer. + + +### func (*UART) ReadByte + +```go +func (uart *UART) ReadByte() (byte, error) +``` + +ReadByte reads a single byte from the RX buffer. +If there is no data in the buffer, returns an error. + + +### func (*UART) Receive + +```go +func (uart *UART) Receive(data byte) +``` + +Receive handles adding data to the UART's data buffer. +Usually called by the IRQ handler for a machine. + + +### func (*UART) SetBaudRate + +```go +func (uart *UART) SetBaudRate(br uint32) +``` + +SetBaudRate sets the communication speed for the UART. + + +### func (*UART) Write + +```go +func (uart *UART) Write(data []byte) (n int, err error) +``` + +Write data over the UART's Tx. +This function blocks until the data is finished being sent. + + +### func (*UART) WriteByte + +```go +func (uart *UART) WriteByte(c byte) error +``` + +WriteByte writes a byte of data over the UART's Tx. +This function blocks until the data is finished being sent. + + + + +## type UARTConfig + +```go +type UARTConfig struct { + BaudRate uint32 + TX Pin + RX Pin + RTS Pin + CTS Pin +} +``` + +UARTConfig is a struct with which a UART (or similar object) can be +configured. The baud rate is usually respected, but TX and RX may be ignored +depending on the chip and the type of object. + + + + + +## type UARTParity + +```go +type UARTParity uint8 +``` + +UARTParity is the parity setting to be used for UART communication. + + + + + diff --git a/content/docs/reference/microcontrollers/machine/qtpy-esp32c3.md b/content/docs/reference/microcontrollers/machine/qtpy-esp32c3.md new file mode 100644 index 00000000..e230a931 --- /dev/null +++ b/content/docs/reference/microcontrollers/machine/qtpy-esp32c3.md @@ -0,0 +1,1115 @@ + +--- +title: qtpy-esp32c3 +--- + + +## Constants + +```go +const ( + D0 = GPIO4 + D1 = GPIO3 + D2 = GPIO1 + D3 = GPIO0 +) +``` + +Digital Pins + + +```go +const ( + A0 = GPIO4 + A1 = GPIO3 + A2 = GPIO1 + A3 = GPIO0 +) +``` + +Analog pins (ADC1) + + +```go +const ( + RX_PIN = GPIO20 + TX_PIN = GPIO21 + + UART_RX_PIN = RX_PIN + UART_TX_PIN = TX_PIN +) +``` + +UART pins + + +```go +const ( + SDA_PIN = GPIO5 + SCL_PIN = GPIO6 + + I2C0_SDA_PIN = SDA_PIN + I2C0_SCL_PIN = SCL_PIN +) +``` + +I2C pins + + +```go +const ( + SCK_PIN = GPIO10 + MI_PIN = GPIO8 + MO_PIN = GPIO7 + + SPI_SCK_PIN = SCK_PIN + SPI_SDI_PIN = MI_PIN + SPI_SDO_PIN = MO_PIN +) +``` + +SPI pins + + +```go +const ( + NEOPIXEL = GPIO2 + WS2812 = GPIO2 + + // also used for boot button. + // set it to be an input-with-pullup + BUTTON = GPIO9 +) +``` + + + +```go +const ( + TWI_FREQ_100KHZ = 100000 + TWI_FREQ_400KHZ = 400000 +) +``` + +TWI_FREQ is the I2C bus speed. Normally either 100 kHz, or 400 kHz for high-speed bus. + +Deprecated: use 100 * machine.KHz or 400 * machine.KHz instead. + + +```go +const ( + // I2CReceive indicates target has received a message from the controller. + I2CReceive I2CTargetEvent = iota + + // I2CRequest indicates the controller is expecting a message from the target. + I2CRequest + + // I2CFinish indicates the controller has ended the transaction. + // + // I2C controllers can chain multiple receive/request messages without + // relinquishing the bus by doing 'restarts'. I2CFinish indicates the + // bus has been relinquished by an I2C 'stop'. + I2CFinish +) +``` + + + +```go +const ( + // I2CModeController represents an I2C peripheral in controller mode. + I2CModeController I2CMode = iota + + // I2CModeTarget represents an I2C peripheral in target mode. + I2CModeTarget +) +``` + + + +```go +const Device = deviceName +``` + +Device is the running program's chip name, such as "ATSAMD51J19A" or +"nrf52840". It is not the same as the CPU name. + +The constant is some hardcoded default value if the program does not target a +particular chip but instead runs in WebAssembly for example. + + +```go +const ( + KHz = 1000 + MHz = 1000_000 + GHz = 1000_000_000 +) +``` + +Generic constants. + + +```go +const NoPin = Pin(0xff) +``` + +NoPin explicitly indicates "not a pin". Use this pin if you want to leave one +of the pins in a peripheral unconfigured (if supported by the hardware). + + +```go +const ( + PinOutput PinMode = iota + PinInput + PinInputPullup + PinInputPulldown +) +``` + + + +```go +const ( + GPIO0 Pin = 0 + GPIO1 Pin = 1 + GPIO2 Pin = 2 + GPIO3 Pin = 3 + GPIO4 Pin = 4 + GPIO5 Pin = 5 + GPIO6 Pin = 6 + GPIO7 Pin = 7 + GPIO8 Pin = 8 + GPIO9 Pin = 9 + GPIO10 Pin = 10 + GPIO11 Pin = 11 + GPIO12 Pin = 12 + GPIO13 Pin = 13 + GPIO14 Pin = 14 + GPIO15 Pin = 15 + GPIO16 Pin = 16 + GPIO17 Pin = 17 + GPIO18 Pin = 18 + GPIO19 Pin = 19 + GPIO20 Pin = 20 + GPIO21 Pin = 21 +) +``` + + + +```go +const ( + PinRising PinChange = iota + 1 + PinFalling + PinToggle +) +``` + +Pin change interrupt constants for SetInterrupt. + + +```go +const ( + SPI_MODE0 = uint8(0) + SPI_MODE1 = uint8(1) + SPI_MODE2 = uint8(2) + SPI_MODE3 = uint8(3) + + FSPICLK_IN_IDX = uint32(63) + FSPICLK_OUT_IDX = uint32(63) + FSPIQ_IN_IDX = uint32(64) + FSPIQ_OUT_IDX = uint32(64) + FSPID_IN_IDX = uint32(65) + FSPID_OUT_IDX = uint32(65) + FSPIHD_IN_IDX = uint32(66) + FSPIHD_OUT_IDX = uint32(66) + FSPIWP_IN_IDX = uint32(67) + FSPIWP_OUT_IDX = uint32(67) + FSPICS0_IN_IDX = uint32(68) + FSPICS0_OUT_IDX = uint32(68) + FSPICS1_OUT_IDX = uint32(69) + FSPICS2_OUT_IDX = uint32(70) + FSPICS3_OUT_IDX = uint32(71) + FSPICS4_OUT_IDX = uint32(72) + FSPICS5_OUT_IDX = uint32(73) +) +``` + + + +```go +const ( + // ParityNone means to not use any parity checking. This is + // the most common setting. + ParityNone UARTParity = iota + + // ParityEven means to expect that the total number of 1 bits sent + // should be an even number. + ParityEven + + // ParityOdd means to expect that the total number of 1 bits sent + // should be an odd number. + ParityOdd +) +``` + + + + + + +## Variables + +```go +var ( + ErrTimeoutRNG = errors.New("machine: RNG Timeout") + ErrClockRNG = errors.New("machine: RNG Clock Error") + ErrSeedRNG = errors.New("machine: RNG Seed Error") + ErrInvalidInputPin = errors.New("machine: invalid input pin") + ErrInvalidOutputPin = errors.New("machine: invalid output pin") + ErrInvalidClockPin = errors.New("machine: invalid clock pin") + ErrInvalidDataPin = errors.New("machine: invalid data pin") + ErrNoPinChangeChannel = errors.New("machine: no channel available for pin interrupt") +) +``` + + + +```go +var ( + DefaultUART = UART0 + + UART0 = &_UART0 + _UART0 = UART{Bus: esp.UART0, Buffer: NewRingBuffer()} + UART1 = &_UART1 + _UART1 = UART{Bus: esp.UART1, Buffer: NewRingBuffer()} + + onceUart = sync.Once{} + errSamePins = errors.New("UART: invalid pin combination") + errWrongUART = errors.New("UART: unsupported UARTn") + errWrongBitSize = errors.New("UART: invalid data size") + errWrongStopBitSize = errors.New("UART: invalid bit size") +) +``` + + + +```go +var ( + _USBCDC = &USB_DEVICE{ + Bus: esp.USB_DEVICE, + } + + USBCDC Serialer = _USBCDC +) +``` + + + +```go +var ( + I2C0 = &I2C{} +) +``` + + + +```go +var ( + ErrInvalidSPIBus = errors.New("machine: SPI bus is invalid") + ErrInvalidSPIMode = errors.New("machine: SPI mode is invalid") +) +``` + + + +```go +var ( + // SPI0 and SPI1 are reserved for use by the caching system etc. + SPI2 = SPI{esp.SPI2} +) +``` + + + +```go +var ( + ErrPWMPeriodTooLong = errors.New("pwm: period too long") +) +``` + + + +```go +var Serial Serialer +``` + +Serial is implemented via USB (USB-CDC). + + + + + +### func CPUFrequency + +```go +func CPUFrequency() uint32 +``` + +CPUFrequency returns the current CPU frequency of the chip. +Currently it is a fixed frequency but it may allow changing in the future. + + +### func GetRNG + +```go +func GetRNG() (ret uint32, err error) +``` + +GetRNG returns 32-bit random numbers using the ESP32-C3 true random number generator, +Random numbers are generated based on the thermal noise in the system and the +asynchronous clock mismatch. +For maximum entropy also make sure that the SAR_ADC is enabled. +See esp32-c3_technical_reference_manual_en.pdf p.524 + + +### func InitSerial + +```go +func InitSerial() +``` + + + +### func NewRingBuffer + +```go +func NewRingBuffer() *RingBuffer +``` + +NewRingBuffer returns a new ring buffer. + + + + +## type ADC + +```go +type ADC struct { + Pin Pin +} +``` + + + + + + +## type ADCConfig + +```go +type ADCConfig struct { + Reference uint32 // analog reference voltage (AREF) in millivolts + Resolution uint32 // number of bits for a single conversion (e.g., 8, 10, 12) + Samples uint32 // number of samples for a single conversion (e.g., 4, 8, 16, 32) + SampleTime uint32 // sample time, in microseconds (µs) +} +``` + +ADCConfig holds ADC configuration parameters. If left unspecified, the zero +value of each parameter will use the peripheral's default settings. + + + + + +## type I2C + +```go +type I2C struct{} +``` + + + + +### func (*I2C) Configure + +```go +func (i2c *I2C) Configure(config I2CConfig) error +``` + + + +### func (*I2C) ReadRegister + +```go +func (i2c *I2C) ReadRegister(address uint8, register uint8, data []byte) error +``` + +ReadRegister transmits the register, restarts the connection as a read +operation, and reads the response. + +Many I2C-compatible devices are organized in terms of registers. This method +is a shortcut to easily read such registers. Also, it only works for devices +with 7-bit addresses, which is the vast majority. + + +### func (*I2C) SetBaudRate + +```go +func (i2c *I2C) SetBaudRate(br uint32) error +``` + + + +### func (*I2C) Tx + +```go +func (i2c *I2C) Tx(addr uint16, w, r []byte) (err error) +``` + +Tx does a single I2C transaction at the specified address. +It clocks out the given address, writes the bytes in w, reads back len(r) +bytes and stores them in r, and generates a stop condition on the bus. + + +### func (*I2C) WriteRegister + +```go +func (i2c *I2C) WriteRegister(address uint8, register uint8, data []byte) error +``` + +WriteRegister transmits first the register and then the data to the +peripheral device. + +Many I2C-compatible devices are organized in terms of registers. This method +is a shortcut to easily write to such registers. Also, it only works for +devices with 7-bit addresses, which is the vast majority. + + + + +## type I2CConfig + +```go +type I2CConfig struct { + Frequency uint32 // in Hz + SCL Pin + SDA Pin +} +``` + +I2CConfig is used to store config info for I2C. + + + + + +## type I2CMode + +```go +type I2CMode int +``` + +I2CMode determines if an I2C peripheral is in Controller or Target mode. + + + + + +## type I2CTargetEvent + +```go +type I2CTargetEvent uint8 +``` + +I2CTargetEvent reflects events on the I2C bus + + + + + +## type NullSerial + +```go +type NullSerial struct { +} +``` + +NullSerial is a serial version of /dev/null (or null router): it drops +everything that is written to it. + + + +### func (NullSerial) Buffered + +```go +func (ns NullSerial) Buffered() int +``` + +Buffered returns how many bytes are buffered in the UART. It always returns 0 +as there are no bytes to read. + + +### func (NullSerial) Configure + +```go +func (ns NullSerial) Configure(config UARTConfig) error +``` + +Configure does nothing: the null serial has no configuration. + + +### func (NullSerial) ReadByte + +```go +func (ns NullSerial) ReadByte() (byte, error) +``` + +ReadByte always returns an error because there aren't any bytes to read. + + +### func (NullSerial) Write + +```go +func (ns NullSerial) Write(p []byte) (n int, err error) +``` + +Write is a no-op: none of the data is being written and it will not return an +error. + + +### func (NullSerial) WriteByte + +```go +func (ns NullSerial) WriteByte(b byte) error +``` + +WriteByte is a no-op: the null serial doesn't write bytes. + + + + +## type PDMConfig + +```go +type PDMConfig struct { + Stereo bool + DIN Pin + CLK Pin +} +``` + + + + + + +## type PWMConfig + +```go +type PWMConfig struct { + // PWM period in nanosecond. Leaving this zero will pick a reasonable period + // value for use with LEDs. + // If you want to configure a frequency instead of a period, you can use the + // following formula to calculate a period from a frequency: + // + // period = 1e9 / frequency + // + Period uint64 +} +``` + +PWMConfig allows setting some configuration while configuring a PWM +peripheral. A zero PWMConfig is ready to use for simple applications such as +dimming LEDs. + + + + + +## type Pin + +```go +type Pin uint8 +``` + +Pin is a single pin on a chip, which may be connected to other hardware +devices. It can either be used directly as GPIO pin or it can be used in +other peripherals like ADC, I2C, etc. + + + +### func (Pin) Configure + +```go +func (p Pin) Configure(config PinConfig) +``` + +Configure this pin with the given configuration. + + +### func (Pin) Get + +```go +func (p Pin) Get() bool +``` + +Get returns the current value of a GPIO pin when configured as an input or as +an output. + + +### func (Pin) High + +```go +func (p Pin) High() +``` + +High sets this GPIO pin to high, assuming it has been configured as an output +pin. It is hardware dependent (and often undefined) what happens if you set a +pin to high that is not configured as an output pin. + + +### func (Pin) Low + +```go +func (p Pin) Low() +``` + +Low sets this GPIO pin to low, assuming it has been configured as an output +pin. It is hardware dependent (and often undefined) what happens if you set a +pin to low that is not configured as an output pin. + + +### func (Pin) PortMaskClear + +```go +func (p Pin) PortMaskClear() (*uint32, uint32) +``` + +Return the register and mask to disable a given GPIO pin. This can be used to +implement bit-banged drivers. + +Warning: only use this on an output pin! + + +### func (Pin) PortMaskSet + +```go +func (p Pin) PortMaskSet() (*uint32, uint32) +``` + +Return the register and mask to enable a given GPIO pin. This can be used to +implement bit-banged drivers. + +Warning: only use this on an output pin! + + +### func (Pin) Set + +```go +func (p Pin) Set(value bool) +``` + +Set the pin to high or low. +Warning: only use this on an output pin! + + +### func (Pin) SetInterrupt + +```go +func (p Pin) SetInterrupt(change PinChange, callback func(Pin)) (err error) +``` + +SetInterrupt sets an interrupt to be executed when a particular pin changes +state. The pin should already be configured as an input, including a pull up +or down if no external pull is provided. + +You can pass a nil func to unset the pin change interrupt. If you do so, +the change parameter is ignored and can be set to any value (such as 0). +If the pin is already configured with a callback, you must first unset +this pins interrupt before you can set a new callback. + + + + +## type PinChange + +```go +type PinChange uint8 +``` + + + + + + +## type PinConfig + +```go +type PinConfig struct { + Mode PinMode +} +``` + + + + + + +## type PinMode + +```go +type PinMode uint8 +``` + +PinMode sets the direction and pull mode of the pin. For example, PinOutput +sets the pin as an output and PinInputPullup sets the pin as an input with a +pull-up. + + + + + +## type RingBuffer + +```go +type RingBuffer struct { + rxbuffer [bufferSize]volatile.Register8 + head volatile.Register8 + tail volatile.Register8 +} +``` + +RingBuffer is ring buffer implementation inspired by post at +https://www.embeddedrelated.com/showthread/comp.arch.embedded/77084-1.php + + + +### func (*RingBuffer) Clear + +```go +func (rb *RingBuffer) Clear() +``` + +Clear resets the head and tail pointer to zero. + + +### func (*RingBuffer) Get + +```go +func (rb *RingBuffer) Get() (byte, bool) +``` + +Get returns a byte from the buffer. If the buffer is empty, +the method will return a false as the second value. + + +### func (*RingBuffer) Put + +```go +func (rb *RingBuffer) Put(val byte) bool +``` + +Put stores a byte in the buffer. If the buffer is already +full, the method will return false. + + +### func (*RingBuffer) Used + +```go +func (rb *RingBuffer) Used() uint8 +``` + +Used returns how many bytes in buffer have been used. + + + + +## type SPI + +```go +type SPI struct { + Bus *esp.SPI2_Type +} +``` + +Serial Peripheral Interface on the ESP32-C3. + + + +### func (SPI) Configure + +```go +func (spi SPI) Configure(config SPIConfig) error +``` + +Configure and make the SPI peripheral ready to use. + + +### func (SPI) Transfer + +```go +func (spi SPI) Transfer(w byte) (byte, error) +``` + +Transfer writes/reads a single byte using the SPI interface. If you need to +transfer larger amounts of data, Tx will be faster. + + +### func (SPI) Tx + +```go +func (spi SPI) Tx(w, r []byte) error +``` + +Tx handles read/write operation for SPI interface. Since SPI is a syncronous write/read +interface, there must always be the same number of bytes written as bytes read. +This is accomplished by sending zero bits if r is bigger than w or discarding +the incoming data if w is bigger than r. + + + + +## type SPIConfig + +```go +type SPIConfig struct { + Frequency uint32 + SCK Pin // Serial Clock + SDO Pin // Serial Data Out (MOSI) + SDI Pin // Serial Data In (MISO) + CS Pin // Chip Select (optional) + LSBFirst bool // MSB is default + Mode uint8 // SPI_MODE0 is default +} +``` + +SPIConfig is used to store config info for SPI. + + + + + +## type Serialer + +```go +type Serialer interface { + WriteByte(c byte) error + Write(data []byte) (n int, err error) + Configure(config UARTConfig) error + Buffered() int + ReadByte() (byte, error) + DTR() bool + RTS() bool +} +``` + + + + + + +## type UART + +```go +type UART struct { + Bus *esp.UART_Type + Buffer *RingBuffer + ParityErrorDetected bool // set when parity error detected + DataErrorDetected bool // set when data corruption detected + DataOverflowDetected bool // set when data overflow detected in UART FIFO buffer or RingBuffer +} +``` + + + + +### func (*UART) Buffered + +```go +func (uart *UART) Buffered() int +``` + +Buffered returns the number of bytes currently stored in the RX buffer. + + +### func (*UART) Configure + +```go +func (uart *UART) Configure(config UARTConfig) error +``` + + + +### func (*UART) Read + +```go +func (uart *UART) Read(data []byte) (n int, err error) +``` + +Read from the RX buffer. + + +### func (*UART) ReadByte + +```go +func (uart *UART) ReadByte() (byte, error) +``` + +ReadByte reads a single byte from the RX buffer. +If there is no data in the buffer, returns an error. + + +### func (*UART) Receive + +```go +func (uart *UART) Receive(data byte) +``` + +Receive handles adding data to the UART's data buffer. +Usually called by the IRQ handler for a machine. + + +### func (*UART) SetBaudRate + +```go +func (uart *UART) SetBaudRate(baudRate uint32) +``` + + + +### func (*UART) SetFormat + +```go +func (uart *UART) SetFormat(dataBits, stopBits int, parity UARTParity) error +``` + + + +### func (*UART) Write + +```go +func (uart *UART) Write(data []byte) (n int, err error) +``` + +Write data over the UART's Tx. +This function blocks until the data is finished being sent. + + +### func (*UART) WriteByte + +```go +func (uart *UART) WriteByte(c byte) error +``` + +WriteByte writes a byte of data over the UART's Tx. +This function blocks until the data is finished being sent. + + + + +## type UARTConfig + +```go +type UARTConfig struct { + BaudRate uint32 + TX Pin + RX Pin + RTS Pin + CTS Pin +} +``` + +UARTConfig is a struct with which a UART (or similar object) can be +configured. The baud rate is usually respected, but TX and RX may be ignored +depending on the chip and the type of object. + + + + + +## type UARTParity + +```go +type UARTParity uint8 +``` + +UARTParity is the parity setting to be used for UART communication. + + + + + +## type USB_DEVICE + +```go +type USB_DEVICE struct { + Bus *esp.USB_DEVICE_Type +} +``` + +USB Serial/JTAG Controller +See esp32-c3_technical_reference_manual_en.pdf +pg. 736 + + + +### func (*USB_DEVICE) Buffered + +```go +func (usbdev *USB_DEVICE) Buffered() int +``` + + + +### func (*USB_DEVICE) Configure + +```go +func (usbdev *USB_DEVICE) Configure(config UARTConfig) error +``` + + + +### func (*USB_DEVICE) DTR + +```go +func (usbdev *USB_DEVICE) DTR() bool +``` + + + +### func (*USB_DEVICE) RTS + +```go +func (usbdev *USB_DEVICE) RTS() bool +``` + + + +### func (*USB_DEVICE) ReadByte + +```go +func (usbdev *USB_DEVICE) ReadByte() (byte, error) +``` + + + +### func (*USB_DEVICE) Write + +```go +func (usbdev *USB_DEVICE) Write(data []byte) (n int, err error) +``` + + + +### func (*USB_DEVICE) WriteByte + +```go +func (usbdev *USB_DEVICE) WriteByte(c byte) error +``` + + + + + diff --git a/content/docs/reference/microcontrollers/machine/xiao-esp32c3.md b/content/docs/reference/microcontrollers/machine/xiao-esp32c3.md new file mode 100644 index 00000000..28e256f5 --- /dev/null +++ b/content/docs/reference/microcontrollers/machine/xiao-esp32c3.md @@ -0,0 +1,1099 @@ + +--- +title: xiao-esp32c3 +--- + + +## Constants + +```go +const ( + D0 = GPIO2 + D1 = GPIO3 + D2 = GPIO4 + D3 = GPIO5 + D4 = GPIO6 + D5 = GPIO7 + D6 = GPIO21 + D7 = GPIO20 + D8 = GPIO8 + D9 = GPIO9 + D10 = GPIO10 +) +``` + +Digital Pins + + +```go +const ( + A0 = GPIO2 + A1 = GPIO3 + A2 = GPIO4 + A3 = GPIO5 +) +``` + +Analog pins + + +```go +const ( + UART_RX_PIN = GPIO20 + UART_TX_PIN = GPIO21 +) +``` + +UART pins + + +```go +const ( + SDA_PIN = GPIO6 + SCL_PIN = GPIO7 +) +``` + +I2C pins + + +```go +const ( + SPI_SCK_PIN = GPIO8 + SPI_SDI_PIN = GPIO9 + SPI_SDO_PIN = GPIO10 +) +``` + +SPI pins + + +```go +const ( + TWI_FREQ_100KHZ = 100000 + TWI_FREQ_400KHZ = 400000 +) +``` + +TWI_FREQ is the I2C bus speed. Normally either 100 kHz, or 400 kHz for high-speed bus. + +Deprecated: use 100 * machine.KHz or 400 * machine.KHz instead. + + +```go +const ( + // I2CReceive indicates target has received a message from the controller. + I2CReceive I2CTargetEvent = iota + + // I2CRequest indicates the controller is expecting a message from the target. + I2CRequest + + // I2CFinish indicates the controller has ended the transaction. + // + // I2C controllers can chain multiple receive/request messages without + // relinquishing the bus by doing 'restarts'. I2CFinish indicates the + // bus has been relinquished by an I2C 'stop'. + I2CFinish +) +``` + + + +```go +const ( + // I2CModeController represents an I2C peripheral in controller mode. + I2CModeController I2CMode = iota + + // I2CModeTarget represents an I2C peripheral in target mode. + I2CModeTarget +) +``` + + + +```go +const Device = deviceName +``` + +Device is the running program's chip name, such as "ATSAMD51J19A" or +"nrf52840". It is not the same as the CPU name. + +The constant is some hardcoded default value if the program does not target a +particular chip but instead runs in WebAssembly for example. + + +```go +const ( + KHz = 1000 + MHz = 1000_000 + GHz = 1000_000_000 +) +``` + +Generic constants. + + +```go +const NoPin = Pin(0xff) +``` + +NoPin explicitly indicates "not a pin". Use this pin if you want to leave one +of the pins in a peripheral unconfigured (if supported by the hardware). + + +```go +const ( + PinOutput PinMode = iota + PinInput + PinInputPullup + PinInputPulldown +) +``` + + + +```go +const ( + GPIO0 Pin = 0 + GPIO1 Pin = 1 + GPIO2 Pin = 2 + GPIO3 Pin = 3 + GPIO4 Pin = 4 + GPIO5 Pin = 5 + GPIO6 Pin = 6 + GPIO7 Pin = 7 + GPIO8 Pin = 8 + GPIO9 Pin = 9 + GPIO10 Pin = 10 + GPIO11 Pin = 11 + GPIO12 Pin = 12 + GPIO13 Pin = 13 + GPIO14 Pin = 14 + GPIO15 Pin = 15 + GPIO16 Pin = 16 + GPIO17 Pin = 17 + GPIO18 Pin = 18 + GPIO19 Pin = 19 + GPIO20 Pin = 20 + GPIO21 Pin = 21 +) +``` + + + +```go +const ( + PinRising PinChange = iota + 1 + PinFalling + PinToggle +) +``` + +Pin change interrupt constants for SetInterrupt. + + +```go +const ( + SPI_MODE0 = uint8(0) + SPI_MODE1 = uint8(1) + SPI_MODE2 = uint8(2) + SPI_MODE3 = uint8(3) + + FSPICLK_IN_IDX = uint32(63) + FSPICLK_OUT_IDX = uint32(63) + FSPIQ_IN_IDX = uint32(64) + FSPIQ_OUT_IDX = uint32(64) + FSPID_IN_IDX = uint32(65) + FSPID_OUT_IDX = uint32(65) + FSPIHD_IN_IDX = uint32(66) + FSPIHD_OUT_IDX = uint32(66) + FSPIWP_IN_IDX = uint32(67) + FSPIWP_OUT_IDX = uint32(67) + FSPICS0_IN_IDX = uint32(68) + FSPICS0_OUT_IDX = uint32(68) + FSPICS1_OUT_IDX = uint32(69) + FSPICS2_OUT_IDX = uint32(70) + FSPICS3_OUT_IDX = uint32(71) + FSPICS4_OUT_IDX = uint32(72) + FSPICS5_OUT_IDX = uint32(73) +) +``` + + + +```go +const ( + // ParityNone means to not use any parity checking. This is + // the most common setting. + ParityNone UARTParity = iota + + // ParityEven means to expect that the total number of 1 bits sent + // should be an even number. + ParityEven + + // ParityOdd means to expect that the total number of 1 bits sent + // should be an odd number. + ParityOdd +) +``` + + + + + + +## Variables + +```go +var ( + ErrTimeoutRNG = errors.New("machine: RNG Timeout") + ErrClockRNG = errors.New("machine: RNG Clock Error") + ErrSeedRNG = errors.New("machine: RNG Seed Error") + ErrInvalidInputPin = errors.New("machine: invalid input pin") + ErrInvalidOutputPin = errors.New("machine: invalid output pin") + ErrInvalidClockPin = errors.New("machine: invalid clock pin") + ErrInvalidDataPin = errors.New("machine: invalid data pin") + ErrNoPinChangeChannel = errors.New("machine: no channel available for pin interrupt") +) +``` + + + +```go +var ( + DefaultUART = UART0 + + UART0 = &_UART0 + _UART0 = UART{Bus: esp.UART0, Buffer: NewRingBuffer()} + UART1 = &_UART1 + _UART1 = UART{Bus: esp.UART1, Buffer: NewRingBuffer()} + + onceUart = sync.Once{} + errSamePins = errors.New("UART: invalid pin combination") + errWrongUART = errors.New("UART: unsupported UARTn") + errWrongBitSize = errors.New("UART: invalid data size") + errWrongStopBitSize = errors.New("UART: invalid bit size") +) +``` + + + +```go +var ( + _USBCDC = &USB_DEVICE{ + Bus: esp.USB_DEVICE, + } + + USBCDC Serialer = _USBCDC +) +``` + + + +```go +var ( + I2C0 = &I2C{} +) +``` + + + +```go +var ( + ErrInvalidSPIBus = errors.New("machine: SPI bus is invalid") + ErrInvalidSPIMode = errors.New("machine: SPI mode is invalid") +) +``` + + + +```go +var ( + // SPI0 and SPI1 are reserved for use by the caching system etc. + SPI2 = SPI{esp.SPI2} +) +``` + + + +```go +var ( + ErrPWMPeriodTooLong = errors.New("pwm: period too long") +) +``` + + + +```go +var Serial Serialer +``` + +Serial is implemented via USB (USB-CDC). + + + + + +### func CPUFrequency + +```go +func CPUFrequency() uint32 +``` + +CPUFrequency returns the current CPU frequency of the chip. +Currently it is a fixed frequency but it may allow changing in the future. + + +### func GetRNG + +```go +func GetRNG() (ret uint32, err error) +``` + +GetRNG returns 32-bit random numbers using the ESP32-C3 true random number generator, +Random numbers are generated based on the thermal noise in the system and the +asynchronous clock mismatch. +For maximum entropy also make sure that the SAR_ADC is enabled. +See esp32-c3_technical_reference_manual_en.pdf p.524 + + +### func InitSerial + +```go +func InitSerial() +``` + + + +### func NewRingBuffer + +```go +func NewRingBuffer() *RingBuffer +``` + +NewRingBuffer returns a new ring buffer. + + + + +## type ADC + +```go +type ADC struct { + Pin Pin +} +``` + + + + + + +## type ADCConfig + +```go +type ADCConfig struct { + Reference uint32 // analog reference voltage (AREF) in millivolts + Resolution uint32 // number of bits for a single conversion (e.g., 8, 10, 12) + Samples uint32 // number of samples for a single conversion (e.g., 4, 8, 16, 32) + SampleTime uint32 // sample time, in microseconds (µs) +} +``` + +ADCConfig holds ADC configuration parameters. If left unspecified, the zero +value of each parameter will use the peripheral's default settings. + + + + + +## type I2C + +```go +type I2C struct{} +``` + + + + +### func (*I2C) Configure + +```go +func (i2c *I2C) Configure(config I2CConfig) error +``` + + + +### func (*I2C) ReadRegister + +```go +func (i2c *I2C) ReadRegister(address uint8, register uint8, data []byte) error +``` + +ReadRegister transmits the register, restarts the connection as a read +operation, and reads the response. + +Many I2C-compatible devices are organized in terms of registers. This method +is a shortcut to easily read such registers. Also, it only works for devices +with 7-bit addresses, which is the vast majority. + + +### func (*I2C) SetBaudRate + +```go +func (i2c *I2C) SetBaudRate(br uint32) error +``` + + + +### func (*I2C) Tx + +```go +func (i2c *I2C) Tx(addr uint16, w, r []byte) (err error) +``` + +Tx does a single I2C transaction at the specified address. +It clocks out the given address, writes the bytes in w, reads back len(r) +bytes and stores them in r, and generates a stop condition on the bus. + + +### func (*I2C) WriteRegister + +```go +func (i2c *I2C) WriteRegister(address uint8, register uint8, data []byte) error +``` + +WriteRegister transmits first the register and then the data to the +peripheral device. + +Many I2C-compatible devices are organized in terms of registers. This method +is a shortcut to easily write to such registers. Also, it only works for +devices with 7-bit addresses, which is the vast majority. + + + + +## type I2CConfig + +```go +type I2CConfig struct { + Frequency uint32 // in Hz + SCL Pin + SDA Pin +} +``` + +I2CConfig is used to store config info for I2C. + + + + + +## type I2CMode + +```go +type I2CMode int +``` + +I2CMode determines if an I2C peripheral is in Controller or Target mode. + + + + + +## type I2CTargetEvent + +```go +type I2CTargetEvent uint8 +``` + +I2CTargetEvent reflects events on the I2C bus + + + + + +## type NullSerial + +```go +type NullSerial struct { +} +``` + +NullSerial is a serial version of /dev/null (or null router): it drops +everything that is written to it. + + + +### func (NullSerial) Buffered + +```go +func (ns NullSerial) Buffered() int +``` + +Buffered returns how many bytes are buffered in the UART. It always returns 0 +as there are no bytes to read. + + +### func (NullSerial) Configure + +```go +func (ns NullSerial) Configure(config UARTConfig) error +``` + +Configure does nothing: the null serial has no configuration. + + +### func (NullSerial) ReadByte + +```go +func (ns NullSerial) ReadByte() (byte, error) +``` + +ReadByte always returns an error because there aren't any bytes to read. + + +### func (NullSerial) Write + +```go +func (ns NullSerial) Write(p []byte) (n int, err error) +``` + +Write is a no-op: none of the data is being written and it will not return an +error. + + +### func (NullSerial) WriteByte + +```go +func (ns NullSerial) WriteByte(b byte) error +``` + +WriteByte is a no-op: the null serial doesn't write bytes. + + + + +## type PDMConfig + +```go +type PDMConfig struct { + Stereo bool + DIN Pin + CLK Pin +} +``` + + + + + + +## type PWMConfig + +```go +type PWMConfig struct { + // PWM period in nanosecond. Leaving this zero will pick a reasonable period + // value for use with LEDs. + // If you want to configure a frequency instead of a period, you can use the + // following formula to calculate a period from a frequency: + // + // period = 1e9 / frequency + // + Period uint64 +} +``` + +PWMConfig allows setting some configuration while configuring a PWM +peripheral. A zero PWMConfig is ready to use for simple applications such as +dimming LEDs. + + + + + +## type Pin + +```go +type Pin uint8 +``` + +Pin is a single pin on a chip, which may be connected to other hardware +devices. It can either be used directly as GPIO pin or it can be used in +other peripherals like ADC, I2C, etc. + + + +### func (Pin) Configure + +```go +func (p Pin) Configure(config PinConfig) +``` + +Configure this pin with the given configuration. + + +### func (Pin) Get + +```go +func (p Pin) Get() bool +``` + +Get returns the current value of a GPIO pin when configured as an input or as +an output. + + +### func (Pin) High + +```go +func (p Pin) High() +``` + +High sets this GPIO pin to high, assuming it has been configured as an output +pin. It is hardware dependent (and often undefined) what happens if you set a +pin to high that is not configured as an output pin. + + +### func (Pin) Low + +```go +func (p Pin) Low() +``` + +Low sets this GPIO pin to low, assuming it has been configured as an output +pin. It is hardware dependent (and often undefined) what happens if you set a +pin to low that is not configured as an output pin. + + +### func (Pin) PortMaskClear + +```go +func (p Pin) PortMaskClear() (*uint32, uint32) +``` + +Return the register and mask to disable a given GPIO pin. This can be used to +implement bit-banged drivers. + +Warning: only use this on an output pin! + + +### func (Pin) PortMaskSet + +```go +func (p Pin) PortMaskSet() (*uint32, uint32) +``` + +Return the register and mask to enable a given GPIO pin. This can be used to +implement bit-banged drivers. + +Warning: only use this on an output pin! + + +### func (Pin) Set + +```go +func (p Pin) Set(value bool) +``` + +Set the pin to high or low. +Warning: only use this on an output pin! + + +### func (Pin) SetInterrupt + +```go +func (p Pin) SetInterrupt(change PinChange, callback func(Pin)) (err error) +``` + +SetInterrupt sets an interrupt to be executed when a particular pin changes +state. The pin should already be configured as an input, including a pull up +or down if no external pull is provided. + +You can pass a nil func to unset the pin change interrupt. If you do so, +the change parameter is ignored and can be set to any value (such as 0). +If the pin is already configured with a callback, you must first unset +this pins interrupt before you can set a new callback. + + + + +## type PinChange + +```go +type PinChange uint8 +``` + + + + + + +## type PinConfig + +```go +type PinConfig struct { + Mode PinMode +} +``` + + + + + + +## type PinMode + +```go +type PinMode uint8 +``` + +PinMode sets the direction and pull mode of the pin. For example, PinOutput +sets the pin as an output and PinInputPullup sets the pin as an input with a +pull-up. + + + + + +## type RingBuffer + +```go +type RingBuffer struct { + rxbuffer [bufferSize]volatile.Register8 + head volatile.Register8 + tail volatile.Register8 +} +``` + +RingBuffer is ring buffer implementation inspired by post at +https://www.embeddedrelated.com/showthread/comp.arch.embedded/77084-1.php + + + +### func (*RingBuffer) Clear + +```go +func (rb *RingBuffer) Clear() +``` + +Clear resets the head and tail pointer to zero. + + +### func (*RingBuffer) Get + +```go +func (rb *RingBuffer) Get() (byte, bool) +``` + +Get returns a byte from the buffer. If the buffer is empty, +the method will return a false as the second value. + + +### func (*RingBuffer) Put + +```go +func (rb *RingBuffer) Put(val byte) bool +``` + +Put stores a byte in the buffer. If the buffer is already +full, the method will return false. + + +### func (*RingBuffer) Used + +```go +func (rb *RingBuffer) Used() uint8 +``` + +Used returns how many bytes in buffer have been used. + + + + +## type SPI + +```go +type SPI struct { + Bus *esp.SPI2_Type +} +``` + +Serial Peripheral Interface on the ESP32-C3. + + + +### func (SPI) Configure + +```go +func (spi SPI) Configure(config SPIConfig) error +``` + +Configure and make the SPI peripheral ready to use. + + +### func (SPI) Transfer + +```go +func (spi SPI) Transfer(w byte) (byte, error) +``` + +Transfer writes/reads a single byte using the SPI interface. If you need to +transfer larger amounts of data, Tx will be faster. + + +### func (SPI) Tx + +```go +func (spi SPI) Tx(w, r []byte) error +``` + +Tx handles read/write operation for SPI interface. Since SPI is a syncronous write/read +interface, there must always be the same number of bytes written as bytes read. +This is accomplished by sending zero bits if r is bigger than w or discarding +the incoming data if w is bigger than r. + + + + +## type SPIConfig + +```go +type SPIConfig struct { + Frequency uint32 + SCK Pin // Serial Clock + SDO Pin // Serial Data Out (MOSI) + SDI Pin // Serial Data In (MISO) + CS Pin // Chip Select (optional) + LSBFirst bool // MSB is default + Mode uint8 // SPI_MODE0 is default +} +``` + +SPIConfig is used to store config info for SPI. + + + + + +## type Serialer + +```go +type Serialer interface { + WriteByte(c byte) error + Write(data []byte) (n int, err error) + Configure(config UARTConfig) error + Buffered() int + ReadByte() (byte, error) + DTR() bool + RTS() bool +} +``` + + + + + + +## type UART + +```go +type UART struct { + Bus *esp.UART_Type + Buffer *RingBuffer + ParityErrorDetected bool // set when parity error detected + DataErrorDetected bool // set when data corruption detected + DataOverflowDetected bool // set when data overflow detected in UART FIFO buffer or RingBuffer +} +``` + + + + +### func (*UART) Buffered + +```go +func (uart *UART) Buffered() int +``` + +Buffered returns the number of bytes currently stored in the RX buffer. + + +### func (*UART) Configure + +```go +func (uart *UART) Configure(config UARTConfig) error +``` + + + +### func (*UART) Read + +```go +func (uart *UART) Read(data []byte) (n int, err error) +``` + +Read from the RX buffer. + + +### func (*UART) ReadByte + +```go +func (uart *UART) ReadByte() (byte, error) +``` + +ReadByte reads a single byte from the RX buffer. +If there is no data in the buffer, returns an error. + + +### func (*UART) Receive + +```go +func (uart *UART) Receive(data byte) +``` + +Receive handles adding data to the UART's data buffer. +Usually called by the IRQ handler for a machine. + + +### func (*UART) SetBaudRate + +```go +func (uart *UART) SetBaudRate(baudRate uint32) +``` + + + +### func (*UART) SetFormat + +```go +func (uart *UART) SetFormat(dataBits, stopBits int, parity UARTParity) error +``` + + + +### func (*UART) Write + +```go +func (uart *UART) Write(data []byte) (n int, err error) +``` + +Write data over the UART's Tx. +This function blocks until the data is finished being sent. + + +### func (*UART) WriteByte + +```go +func (uart *UART) WriteByte(c byte) error +``` + +WriteByte writes a byte of data over the UART's Tx. +This function blocks until the data is finished being sent. + + + + +## type UARTConfig + +```go +type UARTConfig struct { + BaudRate uint32 + TX Pin + RX Pin + RTS Pin + CTS Pin +} +``` + +UARTConfig is a struct with which a UART (or similar object) can be +configured. The baud rate is usually respected, but TX and RX may be ignored +depending on the chip and the type of object. + + + + + +## type UARTParity + +```go +type UARTParity uint8 +``` + +UARTParity is the parity setting to be used for UART communication. + + + + + +## type USB_DEVICE + +```go +type USB_DEVICE struct { + Bus *esp.USB_DEVICE_Type +} +``` + +USB Serial/JTAG Controller +See esp32-c3_technical_reference_manual_en.pdf +pg. 736 + + + +### func (*USB_DEVICE) Buffered + +```go +func (usbdev *USB_DEVICE) Buffered() int +``` + + + +### func (*USB_DEVICE) Configure + +```go +func (usbdev *USB_DEVICE) Configure(config UARTConfig) error +``` + + + +### func (*USB_DEVICE) DTR + +```go +func (usbdev *USB_DEVICE) DTR() bool +``` + + + +### func (*USB_DEVICE) RTS + +```go +func (usbdev *USB_DEVICE) RTS() bool +``` + + + +### func (*USB_DEVICE) ReadByte + +```go +func (usbdev *USB_DEVICE) ReadByte() (byte, error) +``` + + + +### func (*USB_DEVICE) Write + +```go +func (usbdev *USB_DEVICE) Write(data []byte) (n int, err error) +``` + + + +### func (*USB_DEVICE) WriteByte + +```go +func (usbdev *USB_DEVICE) WriteByte(c byte) error +``` + + + + + diff --git a/content/docs/reference/microcontrollers/macropad-rp2040.md b/content/docs/reference/microcontrollers/macropad-rp2040.md index 2157975e..da5afe67 100644 --- a/content/docs/reference/microcontrollers/macropad-rp2040.md +++ b/content/docs/reference/microcontrollers/macropad-rp2040.md @@ -3,7 +3,7 @@ title: "Adafruit MacroPad RP2040" weight: 3 --- -The [Adafruit MacroPad RP2040](https://www.adafruit.com/product/5100) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. +The [MacroPad RP2040](https://www.adafruit.com/product/5100) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. ## Interfaces diff --git a/content/docs/reference/microcontrollers/maixbit.md b/content/docs/reference/microcontrollers/maixbit.md index a3b33add..c7073e93 100644 --- a/content/docs/reference/microcontrollers/maixbit.md +++ b/content/docs/reference/microcontrollers/maixbit.md @@ -80,4 +80,5 @@ You may get the following error when flashing the MAix Bit: ```shell error: unable to locate a serial port ``` + To resolve this, just specify the MAix Bit's serial port when flashing using `tinygo flash -target=maixbit -port=[MAIXBIT PORT] [PATH TO YOUR PROGRAM]`. diff --git a/content/docs/reference/microcontrollers/matrixportal-m4.md b/content/docs/reference/microcontrollers/matrixportal-m4.md index f89c2f06..1e9d1420 100644 --- a/content/docs/reference/microcontrollers/matrixportal-m4.md +++ b/content/docs/reference/microcontrollers/matrixportal-m4.md @@ -3,7 +3,14 @@ title: "Adafruit Matrix Portal M4" weight: 3 --- -The [Adafruit Matrix Portal M4](https://www.adafruit.com/product/4745) is an ARM development system based on the [ATSAMD51J19 Cortex M4 processor](https://www.microchip.com/wwwproducts/en/ATSAMD51J19). The Adafruit Matrix Portal M4 is designed to plugin easily to any HUB-75 LED display. In addition it has a built-in ESP32 Wi-Fi coprocessor, along with a LIS3DH accelerometer. +The [Matrix Portal M4](https://www.adafruit.com/product/4745) is an ARM development system based on the [ATSAMD51J19 Cortex M4 processor](https://www.microchip.com/wwwproducts/en/ATSAMD51J19). The Adafruit Matrix Portal M4 is designed to plugin easily to any HUB-75 LED display. + +## Peripherals and Drivers + +- [LIS3DH](https://pkg.go.dev/tinygo.org/x/drivers/lis3dh) IMU chip (acceleration, tap detection, free-fall detection) +- [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) Neopixel (built-in) +- Buttons +- ESP32 Wi-Fi coprocessor (built-in) ## Interfaces diff --git a/content/docs/reference/microcontrollers/metro-m4-airlift.md b/content/docs/reference/microcontrollers/metro-m4-airlift.md index aa74c796..20c46c59 100644 --- a/content/docs/reference/microcontrollers/metro-m4-airlift.md +++ b/content/docs/reference/microcontrollers/metro-m4-airlift.md @@ -3,7 +3,13 @@ title: "Adafruit Metro M4 Express AirLift" weight: 3 --- -The [Adafruit Metro M4 Express AirLift](https://www.adafruit.com/product/4000) is an ARM development board based on the Atmel [ATSAMD51J19](https://www.microchip.com/wwwproducts/en/ATSAMD51J19) family of SoC that has Arduino shield compatible form factor, and a built-in EspressIf ESP32 Wi-Fi Co processor. +The [Metro M4 Express AirLift](https://www.adafruit.com/product/4000) is an ARM development board based on the Atmel [ATSAMD51J19](https://www.microchip.com/wwwproducts/en/ATSAMD51J19) family of SoC that has Arduino shield compatible +form factor. + +## Peripherals and Drivers + +- [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) Neopixel via the `PB22` pin +- ESP32 Wi-Fi coprocessor (built-in) ## Interfaces @@ -101,5 +107,3 @@ Once you have updated your Metro M4 Express board the first time, after that you ## Notes You can use the USB port to the Metro M4 Express as a serial port. `UART0` refers to this connection. - -The Neopixel LED on the Metro M4 Express can be accessed using the [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) driver via the `PB22` pin diff --git a/content/docs/reference/microcontrollers/microbit.md b/content/docs/reference/microcontrollers/microbit.md index acc1573e..c3e4abd2 100644 --- a/content/docs/reference/microcontrollers/microbit.md +++ b/content/docs/reference/microcontrollers/microbit.md @@ -3,7 +3,16 @@ title: "BBC micro:bit" weight: 3 --- -The BBC [micro:bit](https://microbit.org) is a tiny programmable computer designed for learning. It is based on the Nordic Semiconductor [nRF51822](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF51822) ARM Cortex MO chip. +The [micro:bit](https://microbit.org) is a tiny programmable computer designed for learning. It is based on the +Nordic Semiconductor [nRF51822](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF51822) ARM Cortex MO chip. + +## Peripherals and Drivers + +- [nRF51822](https://github.com/tinygo-org/bluetooth) Bluetooth +- Accelerometer, Magnetometer +- Microphone +- Speaker +- Buttons ## Interfaces @@ -61,9 +70,7 @@ The BBC [micro:bit](https://microbit.org) is a tiny programmable computer design The micro:bit comes with the [DAPLink bootloader](https://tech.microbit.org/software/daplink-interface/) already installed. This means you can just copy the compiled `.hex` file generated by TinyGo onto it, no additional flashing software is needed. - Plug your micro:bit into your computer's USB port. - - The micro:bit board will appear to your computer like a USB drive. - - Build and flash your TinyGo program using `tinygo flash` like this: ```shell @@ -79,7 +86,6 @@ Note that if you want to use the Nordic SoftDevice, you cannot use this flashing An alternative approach to load programs onto the micro:bit is by using the `openocd` command line utility program. You must install [OpenOCD](http://openocd.org/) before you will be able to flash the micro:bit board with your TinyGo code. - Plug your micro:bit into your computer's USB port. - - Build and flash your TinyGo program using `tinygo flash -target=microbit -programmer=cmsis-dap` ## Notes @@ -102,5 +108,3 @@ machine.SPI1.Configure(machine.SPIConfig{ // use I2C0 as normally do machine.I2C0.Configure(machine.I2CConfig{}) ``` - -Bluetooth support is now available for the BBC micro:bit board. See https://github.com/tinygo-org/bluetooth for more information. diff --git a/content/docs/reference/microcontrollers/nano-33-ble-sense.md b/content/docs/reference/microcontrollers/nano-33-ble-sense.md deleted file mode 100644 index 6fbd5958..00000000 --- a/content/docs/reference/microcontrollers/nano-33-ble-sense.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "Arduino Nano 33 BLE Sense" -weight: 3 ---- - -The [Arduino Nano 33 BLE Sense](https://store.arduino.cc/arduino-nano-33-ble-sense) is a very small ARM development board based on the Nordic Semiconductor [nrf52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. - -This is the same board as [Arduino Nano 33 BLE]({{}}) but -with additional onboard sensors (see below). - -Flash this board exactly the same way as -[Arduino Nano 33 BLE]({{}}) (target name is the same too). - -## Additional onboard sensors - -* Proximity [APDS9960](https://github.com/tinygo-org/drivers/tree/release/apds9960) -* Pressure [LPS22HB](https://github.com/tinygo-org/drivers/tree/release/lps22hb) -* Humidity [HTS221](https://github.com/tinygo-org/drivers/tree/release/hts221) -* Microphone [MP34DT06JTR](https://github.com/tinygo-org/drivers/tree/release/microphone) diff --git a/content/docs/reference/microcontrollers/nano-33-ble.md b/content/docs/reference/microcontrollers/nano-33-ble.md index 400ca9b3..ce98ddd9 100644 --- a/content/docs/reference/microcontrollers/nano-33-ble.md +++ b/content/docs/reference/microcontrollers/nano-33-ble.md @@ -1,12 +1,22 @@ --- -title: "Arduino Nano 33 BLE" +title: "Arduino Nano 33 BLE (Sense)" weight: 3 --- -The [Arduino Nano33 BLE](https://store.arduino.cc/arduino-nano-33-ble) is a very small ARM development board based on the Nordic Semiconductor [nrf52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. +The [Arduino Nano 33 BLE](https://store.arduino.cc/arduino-nano-33-ble) is a very small ARM development board based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. -There is also the [Arduino Nano33 BLE Sense]({{}}) -which is the exact same board but with additional onboard sensors. +There is also the [Arduino Nano 33 BLE Sense](https://store.arduino.cc/arduino-nano-33-ble-sense) which is the exact same board but with additional onboard sensors, see below. Flash this board exactly the same way (target name is the same too). + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth +- [LSM9DS1](https://github.com/tinygo-org/drivers/tree/release/lsm9ds1) 9-axis IMU +- [APDS9960](https://github.com/tinygo-org/drivers/tree/release/apds9960) Proximity +- [LPS22HB](https://github.com/tinygo-org/drivers/tree/release/lps22hb) Pressure +- [HTS221](https://github.com/tinygo-org/drivers/tree/release/hts221) Humidity +- [MP34DT06JTR](https://github.com/tinygo-org/drivers/tree/release/microphone) Microphone + +> The sensors are available on the "Sense" version only. ## Interfaces @@ -59,10 +69,6 @@ which is the exact same board but with additional onboard sensors. | `MIC_CLK` | `P0_26` | | | `MIC_DIN` | `P0_25` | | -## Onboard sensors - -* 9-axis IMU: [LSM9DS1](https://github.com/tinygo-org/drivers/tree/release/lsm9ds1) - ## Machine Package Docs [Documentation for the machine package for the Arduino Nano33 BLE](../machine/nano-33-ble) @@ -73,7 +79,7 @@ In order to flash your TinyGo programs onto the Arduino Nano33 BLE board, you wi ### macOS -If you have a Mac computer with an Intel processor, download the `bossac_arduino2` program from http://downloads.arduino.cc/tools/bossac-1.9.1-arduino2-osx.tar.gz +If you have a Mac computer with an Intel processor, download the `bossac_arduino2` program from Extract the downloaded file to a directory on your computer. @@ -81,7 +87,7 @@ Make sure to add that directory into your PATH. ### Linux -Download the `bossac_arduino2` program from http://downloads.arduino.cc/tools/bossac-1.9.1-arduino2-linux64.tar.gz +Download the `bossac_arduino2` program from Extract the downloaded file to a directory on your computer. @@ -89,7 +95,7 @@ Make sure to add that directory into your PATH. ### Windows -Download the `bossac_arduino2` program from http://downloads.arduino.cc/tools/bossac-1.9.1-arduino2-windows.tar.gz +Download the `bossac_arduino2` program from Extract the downloaded file to a directory on your computer. @@ -116,11 +122,11 @@ Instructions needed here. ## Bluetooth -Nordic Semiconductor's SoftDevice (s140v7) must be flashed first to enable use of [bluetooth](https://github.com/tinygo-org/bluetooth) on this board. +Nordic Semiconductor's SoftDevice (s140v7) must be flashed first to enable use of bluetooth on this board. SoftDevice overwrites original bootloader and flashing method described above is not avalable anymore. -Instead, please use [debug]({{}}) probe and -flash your code with `nano-33-ble-s140v7` target. + +Instead, please use [debug]({{}}) probe and flash your code with `nano-33-ble-s140v7` target. ## Notes diff --git a/content/docs/reference/microcontrollers/nano-rp2040.md b/content/docs/reference/microcontrollers/nano-rp2040.md index f2d27361..cf58b68e 100644 --- a/content/docs/reference/microcontrollers/nano-rp2040.md +++ b/content/docs/reference/microcontrollers/nano-rp2040.md @@ -3,11 +3,12 @@ title: "Arduino Nano RP2040 Connect" weight: 3 --- -The [Nano RP2040 Connect](https://store.arduino.cc/nano-rp2040-connect) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. +The [Arduino Nano RP2040 Connect](https://store.arduino.cc/nano-rp2040-connect) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. -Peripherals: -- NINA-W102 chip with [wifinina](https://github.com/tinygo-org/drivers/tree/release/wifinina) firmware (wifi and bluetooth) -- [lsm6dox](https://github.com/tinygo-org/drivers/tree/release/lsm6dox) IMU chip (acceleration, rotation and temperature) +## Peripherals and Drivers + +- [NINA-W102](https://github.com/tinygo-org/drivers/tree/release/wifinina) chip for WiFi and Bluetooth +- [LSM6DOX](https://github.com/tinygo-org/drivers/tree/release/lsm6dox) IMU chip (acceleration, rotation and temperature) - microphone ## Interfaces diff --git a/content/docs/reference/microcontrollers/nicenano.md b/content/docs/reference/microcontrollers/nicenano.md index 2db915bf..14114ac8 100644 --- a/content/docs/reference/microcontrollers/nicenano.md +++ b/content/docs/reference/microcontrollers/nicenano.md @@ -1,9 +1,13 @@ --- -title: "nice!nano" +title: "Nice Keyboards nice!nano" weight: 3 --- -The [nice!nano](https://nicekeyboards.com/products/nice-nano-v1-0) is a wireless, BLE enabled replacement for the Pro Micro powered by the Nordic Semiconductor [nrf52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. +The [nice!nano](https://nicekeyboards.com/products/nice-nano-v1-0) is a wireless, BLE enabled replacement for the Pro Micro powered by the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth ## Interfaces @@ -90,15 +94,13 @@ Once you have updated your nice!nano board the first time, after that you should You can use the USB port to the nice!nano as a serial port. `UART0` refers to this connection. -Bluetooth support is available for the nice!nano board. See https://github.com/tinygo-org/bluetooth for more information. - ## Updating the UF2 bootloader This board uses a UF2 bootloader created by Adafruit: https://github.com/adafruit/Adafruit_nRF52_Bootloader We recommend bootloader version 0.4.1 or above. You can check what version is installed on your board by double-clicking the button on the board to launch the bootloader. When you do this, a USB volume that should automatically be mounted on your computer. Check the file named "INFO_UF2.TXT" on that drive. The bootloader firmware version should be listed in that file, for example: -``` +```shell UF2 Bootloader 0.4.1 lib/nrfx (v2.0.0) lib/tinyusb (0.6.0-272-g4e6aa0d8) lib/uf2 (remotes/origin/configupdate-9-gadbb8c7) Model: Adafruit ItsyBitsy nRF52840 Express Board-ID: nRF52840-ItsyBitsy-revA @@ -106,7 +108,7 @@ SoftDevice: S140 version 6.1.1 Date: Jan 19 2021 ``` -To update the bootloader, you will need to install the `adafruit-nrfutil` program. +To update the bootloader, you will need to install the `adafruit-nrfutil` program. You can install it by running: @@ -114,10 +116,10 @@ You can install it by running: pip3 install --user adafruit-nrfutil ``` -Once you have installed the `adafruit-nrfutil` program, download the firmware here: +Once you have installed the `adafruit-nrfutil` program, download the firmware here: https://github.com/adafruit/Adafruit_nRF52_Bootloader/releases/download/0.4.1/nice_nano_bootloader-0.4.1.zip -Unzip the files in this zip file and save them to a convenient location. +Unzip the files in this zip file and save them to a convenient location. Plug in your board to your computer's USB port. diff --git a/content/docs/reference/microcontrollers/nintendoswitch.md b/content/docs/reference/microcontrollers/nintendoswitch.md index d2e9c45f..fc3b060f 100644 --- a/content/docs/reference/microcontrollers/nintendoswitch.md +++ b/content/docs/reference/microcontrollers/nintendoswitch.md @@ -3,19 +3,19 @@ title: "Nintendo Switch" weight: 3 --- -The [Nintendo Switch](https://en.wikipedia.org/wiki/Nintendo_Switch) is a handheld videogame platform based on the [Nvidia Tegra X1](https://en.wikipedia.org/wiki/Tegra#Tegra_X1) SoC. +The [Switch](https://en.wikipedia.org/wiki/Nintendo_Switch) is a handheld videogame platform based on the [Nvidia Tegra X1](https://en.wikipedia.org/wiki/Tegra#Tegra_X1) SoC. ## Interfaces | Interface | Hardware Supported | TinyGo Support | | --------- | ------------- | ----- | -| GPIO | ? | ? | -| UART | ? | ? | -| SPI | ? | ? | -| I2C | ? | ? | -| ADC | ? | ? | -| PWM | ? | ? | -| USBDevice | ? | ? | +| GPIO | ? | ? | +| UART | ? | ? | +| SPI | ? | ? | +| I2C | ? | ? | +| ADC | ? | ? | +| PWM | ? | ? | +| USBDevice | ? | ? | ## Machine Package Docs @@ -23,9 +23,9 @@ The [Nintendo Switch](https://en.wikipedia.org/wiki/Nintendo_Switch) is a handhe ## Installing dependencies -You will need the `linkle` (https://github.com/MegatonHammer/linkle) program to convert to the NRO format needed by the Switch: +You will need the [linkle](https://github.com/MegatonHammer/linkle) program to convert to the NRO format needed by the Switch. -You can use a Nintendo Switch software emulator such as yuzu (https://yuzu-emu.org/) to test your programs. +You can use a Nintendo Switch software emulator such as [yuzu](https://yuzu-emu.org/) to test your programs. ## Building code @@ -49,6 +49,6 @@ Information needed here... ## Notes -See the gonx package (https://github.com/racerxdl/gonx) for wrappers around Nintendo Switch APIs. +See the [gonx package](https://github.com/racerxdl/gonx) for wrappers around Nintendo Switch APIs. Examples using gonx can be found at https://github.com/racerxdl/go-switch-examples diff --git a/content/docs/reference/microcontrollers/nodemcu.md b/content/docs/reference/microcontrollers/nodemcu.md index 630c2f3d..3a8b712b 100644 --- a/content/docs/reference/microcontrollers/nodemcu.md +++ b/content/docs/reference/microcontrollers/nodemcu.md @@ -3,7 +3,11 @@ title: "ESP8266 - NodeMCU" weight: 3 --- -The [Espressif ESP8266](https://www.espressif.com/en/products/socs/esp8266) NodeMCU is a small yet powerful SoC that is usually used for WiFi applications thanks to its built-in radio. +The [ESP8266 - NodeMCU](https://en.wikipedia.org/wiki/NodeMCU) is based on [Espressif ESP8266](https://www.espressif.com/en/products/socs/esp8266). + +## Peripherals and Drivers + +A small yet powerful SoC that is usually used for WiFi applications thanks to its built-in radio. ## Interfaces @@ -42,7 +46,7 @@ The [Espressif ESP8266](https://www.espressif.com/en/products/socs/esp8266) Node ### CLI Flashing on Linux -You need to install the same toolchain for the ESP8266 as is used for the ESP32 to use the ESP8266 with TinyGo: +You need to install the same toolchain for the ESP8266 as is used for the ESP32 to use the ESP8266 with TinyGo: https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/linux-setup.html#standard-setup-of-toolchain-for-linux @@ -55,7 +59,7 @@ Now you should be able to flash your board as follows: - Plug your ESP8266 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP8266 with the blinky1 example: - ``` + ```shell tinygo flash -target=nodemcu -port=/dev/ttyUSB examples/blinky1 ``` @@ -76,7 +80,7 @@ Now you should be able to flash your board as follows: - Plug your ESP8266 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP8266 with the blinky1 example: - ``` + ```shell tinygo flash -target=nodemcu examples/blinky1 ``` @@ -97,16 +101,8 @@ Now you should be able to flash your board as follows: - Plug your ESP826 board into your computer's USB port. - Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP826 with the blinky1 example: - ``` + ```shell tinygo flash -target=nodemcu examples/blinky1 ``` - The ESP826 board should restart and then begin running your program. - -### Troubleshooting - -Goes here - -## Notes - -Goes here diff --git a/content/docs/reference/microcontrollers/nrf52840-mdk-usb-dongle.md b/content/docs/reference/microcontrollers/nrf52840-mdk-usb-dongle.md index f62fa9e7..681a8477 100644 --- a/content/docs/reference/microcontrollers/nrf52840-mdk-usb-dongle.md +++ b/content/docs/reference/microcontrollers/nrf52840-mdk-usb-dongle.md @@ -3,7 +3,11 @@ title: "Makerdiary nRF52840-MDK USB Dongle" weight: 3 --- -The [nRF52840 MDK USB Dongle](https://wiki.makerdiary.com/nrf52840-mdk-usb-dongle/) (not to be confused with its sibling, the [nRF52840-MDK](https://wiki.makerdiary.com/nrf52840-mdk/)) is an open-source, micro development kit dongle for IoT applications based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) SoC chip. +The [nRF52840-MDK USB Dongle](https://wiki.makerdiary.com/nrf52840-mdk-usb-dongle/) (not to be confused with its sibling, the [Makerdiary nRF52840-MDK](https://wiki.makerdiary.com/nrf52840-mdk/)) is an open-source, micro development kit dongle for IoT applications based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) SoC chip. + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth ## Interfaces @@ -59,5 +63,3 @@ To install the S140 v6 SoftDevice, please follow the SoftDevice part of the ["Ru You can use the USB port of the nRF52840 MDK USB Dongle as a serial port. `UART0` refers to this connection. The button (pin 18) on the nRF52840 MDK USB Dongle can be to be configured as a reset-button or GPIO pin through the `PSELRESET[0]/[1]` UICR registers. When it is configured as reset instead of as GPIO, you won't be able to use the button in your code as pressing it will reset the nrf52840. To set the `PSELRESET[0]/[1]` UICR registers back to their default value (disabled), please flash the [pselreset erase example](https://github.com/makerdiary/nrf52840-mdk-usb-dongle/tree/master/examples/nrf5-sdk/pselreset_erase) using [these instructions](https://wiki.makerdiary.com/nrf52840-mdk-usb-dongle/programming/#dfu-via-uf2-bootloader) on the nRF52840 MDK USB Dongle wiki. - -Bluetooth support is now available for nRF52840 boards. See https://github.com/tinygo-org/bluetooth for more information. diff --git a/content/docs/reference/microcontrollers/nrf52840-mdk.md b/content/docs/reference/microcontrollers/nrf52840-mdk.md index 16844ae6..4eb84a8b 100644 --- a/content/docs/reference/microcontrollers/nrf52840-mdk.md +++ b/content/docs/reference/microcontrollers/nrf52840-mdk.md @@ -3,7 +3,11 @@ title: "Makerdiary nRF52840-MDK" weight: 3 --- -The [nRF52840-MDK](https://wiki.makerdiary.com/nrf52840-mdk/) (not to be confused with its sibling, the [nRF52840-MDK-USB-Dongle](https://wiki.makerdiary.com/nrf52840-mdk-usb-dongle/)) is an open-source, micro development kit for IoT applications based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) SoC chip. +The [nRF52840-MDK](https://wiki.makerdiary.com/nrf52840-mdk/) (not to be confused with its sibling, the [Makerdiary nRF52840-MDK USB Dongle](https://wiki.makerdiary.com/nrf52840-mdk-usb-dongle/)) is an open-source, micro development kit for IoT applications based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) SoC chip. + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth ## Interfaces @@ -58,7 +62,3 @@ Once you have installed both of these correctly, you will be able to flash the n - Plug your nRF52840-MDK into your computer's USB port. - Build and flash your TinyGo program using `tinygo flash -target=nrf52840-mdk -programmer command` - -## Notes - -Bluetooth support is now available for nRF52840 boards. See https://github.com/tinygo-org/bluetooth for more information. diff --git a/content/docs/reference/microcontrollers/nucleo-f103rb.md b/content/docs/reference/microcontrollers/nucleo-f103rb.md index a6751243..75ac6ce1 100644 --- a/content/docs/reference/microcontrollers/nucleo-f103rb.md +++ b/content/docs/reference/microcontrollers/nucleo-f103rb.md @@ -1,9 +1,9 @@ --- -title: 'ST Micro "Nucleo" F103RB' +title: 'ST Micro STM32 Nucleo-64 F103RB' weight: 3 --- -The [Nucleo F103RB](https://www.st.com/en/evaluation-tools/nucleo-f103rb.html) is a rather affordable ARM development board based on the ST Micro [STM32F103RB](https://www.st.com/en/microcontrollers/stm32f103rb.html) SoC providing lots of GPIO pins and an onboard programmer/debugger with mini-USB connector. +The [STM32 Nucleo-64 F103RB](https://www.st.com/en/evaluation-tools/nucleo-f103rb.html) is a rather affordable ARM development board based on the ST Micro [STM32F103RB](https://www.st.com/en/microcontrollers/stm32f103rb.html) SoC providing lots of GPIO pins and an onboard programmer/debugger with mini-USB connector. ## Interfaces diff --git a/content/docs/reference/microcontrollers/nucleo-f722ze.md b/content/docs/reference/microcontrollers/nucleo-f722ze.md index f895b1e9..f8a45b2f 100644 --- a/content/docs/reference/microcontrollers/nucleo-f722ze.md +++ b/content/docs/reference/microcontrollers/nucleo-f722ze.md @@ -1,9 +1,11 @@ --- -title: 'ST Micro "Nucleo" F722ZE' +title: 'ST Micro STM32 Nucleo-144 F722ZE' weight: 3 --- -The [STM32 Nucleo F722ZE](https://www.st.com/en/evaluation-tools/nucleo-f722ze.html) is an ARM development board based on the ST Micro [STM32F722ZE](https://www.st.com/en/microcontrollers-microprocessors/stm32f722ze.html) SoC. +The [STM32 Nucleo-144 F722ZE](https://www.st.com/en/evaluation-tools/nucleo-f722ze.html) is an ARM development board based on the ST Micro [STM32F722ZE](https://www.st.com/en/microcontrollers-microprocessors/stm32f722ze.html) SoC. + +## Peripherals and Drivers It has 2 user buttons, and 3 user LEDs. diff --git a/content/docs/reference/microcontrollers/nucleo-l031k6.md b/content/docs/reference/microcontrollers/nucleo-l031k6.md index 8d39725a..1c3f1dd8 100644 --- a/content/docs/reference/microcontrollers/nucleo-l031k6.md +++ b/content/docs/reference/microcontrollers/nucleo-l031k6.md @@ -1,9 +1,11 @@ --- -title: 'ST Micro "Nucleo" L031K6' +title: 'ST Micro STM32 Nucleo-32 L031K6' weight: 3 --- -The [STM32 Nucleo L031K6](https://www.st.com/en/evaluation-tools/nucleo-l031k6.html) is an ARM development board based on the ST Micro [STM32L031K6](https://www.st.com/en/microcontrollers-microprocessors/stm32l031k6.html) SoC. +The [STM32 Nucleo-32 L031K6](https://www.st.com/en/evaluation-tools/nucleo-l031k6.html) is an ARM development board based on the ST Micro [STM32L031K6](https://www.st.com/en/microcontrollers-microprocessors/stm32l031k6.html) SoC. + +## Peripherals and Drivers It has 2 user buttons, and 3 user LEDs. diff --git a/content/docs/reference/microcontrollers/nucleo-l432kc.md b/content/docs/reference/microcontrollers/nucleo-l432kc.md index d3181564..e376ee0c 100644 --- a/content/docs/reference/microcontrollers/nucleo-l432kc.md +++ b/content/docs/reference/microcontrollers/nucleo-l432kc.md @@ -1,9 +1,11 @@ --- -title: 'ST Micro "Nucleo" L432KC' +title: 'ST Micro STM32 Nucleo-32 L432KC' weight: 3 --- -The [STM32 Nucleo L432KC](https://www.st.com/en/evaluation-tools/nucleo-l432kc.html) is an ARM development board based on the ST Micro [STM32L432KC](https://www.st.com/en/microcontrollers-microprocessors/stm32l432kc.html) SoC. +The [STM32 Nucleo-32 L432KC](https://www.st.com/en/evaluation-tools/nucleo-l432kc.html) is an ARM development board based on the ST Micro [STM32L432KC](https://www.st.com/en/microcontrollers-microprocessors/stm32l432kc.html) SoC. + +## Peripherals and Drivers It has 2 user buttons, and 3 user LEDs. diff --git a/content/docs/reference/microcontrollers/nucleo-l552ze.md b/content/docs/reference/microcontrollers/nucleo-l552ze.md index 4453c3f9..4893b2ea 100644 --- a/content/docs/reference/microcontrollers/nucleo-l552ze.md +++ b/content/docs/reference/microcontrollers/nucleo-l552ze.md @@ -1,9 +1,11 @@ --- -title: 'ST Micro "Nucleo" L552ZE' +title: 'ST Micro STM32 Nucleo-144 L552ZE' weight: 3 --- -The [STM32 Nucleo L552ZE](https://www.st.com/en/evaluation-tools/nucleo-l552ze-q.html) is an ARM development board based on the ST Micro [STM32L552ZE](https://www.st.com/en/microcontrollers-microprocessors/stm32l552ze.html) SoC. +The [STM32 Nucleo-144 L552ZE](https://www.st.com/en/evaluation-tools/nucleo-l552ze-q.html) is an ARM development board based on the ST Micro [STM32L552ZE](https://www.st.com/en/microcontrollers-microprocessors/stm32l552ze.html) SoC. + +## Peripherals and Drivers It has onboard ethernet, 2 user buttons, and 3 user LEDs. diff --git a/content/docs/reference/microcontrollers/nucleo-wl55jc.md b/content/docs/reference/microcontrollers/nucleo-wl55jc.md index 37b618fd..737a2fb5 100644 --- a/content/docs/reference/microcontrollers/nucleo-wl55jc.md +++ b/content/docs/reference/microcontrollers/nucleo-wl55jc.md @@ -1,9 +1,11 @@ --- -title: "STM32 Nucleo WL55JC" +title: "ST Micro STM32WL Nucleo-64 WL55JC" weight: 3 --- -The [STM32 Nucleo WL55JC](https://www.st.com/en/evaluation-tools/nucleo-wl55jc.html) is an ARM development board based on the ST Micro [STM32WL55JCI](https://www.st.com/en/microcontrollers-microprocessors/stm32wl55jc.html) SoC. +The [STM32WL Nucleo-64 WL55JC](https://www.st.com/en/evaluation-tools/nucleo-wl55jc.html) is an ARM development board based on the ST Micro [STM32WL55JCI](https://www.st.com/en/microcontrollers-microprocessors/stm32wl55jc.html) SoC. + +## Peripherals and Drivers It has onboard LoRa®, (G)FSK, (G)MSK, and BPSK as well as 3 user LEDs, 3 user buttons and 1 reset push-button diff --git a/content/docs/reference/microcontrollers/p1am-100.md b/content/docs/reference/microcontrollers/p1am-100.md index dd812931..8c055a33 100644 --- a/content/docs/reference/microcontrollers/p1am-100.md +++ b/content/docs/reference/microcontrollers/p1am-100.md @@ -3,7 +3,13 @@ title: "ProductivityOpen P1AM-100" weight: 3 --- -The [ProductivityOpen P1AM-100](https://facts-engineering.github.io/modules/P1AM-100/P1AM-100.html) automation platform compatible with Productivity1000 Series I/O modules, P1AM Series shields, and Arduino MKR format shields. It is based on the Microchip [SAMD21G18](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of processors. It also has a NINA-W102 chip onboard which provides an wireless communication abilities based on the popular ESP32 family of wireless chips from Espressif. +The [P1AM-100](https://facts-engineering.github.io/modules/P1AM-100/P1AM-100.html) automation platform compatible with Productivity1000 Series I/O modules, P1AM Series shields, and Arduino MKR format shields. It is based on the Microchip [SAMD21G18](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of processors. + +## Peripherals and Drivers + +- [NINA-W102](https://github.com/tinygo-org/drivers/tree/release/wifinina) wireless + +You can also use the Espressif ESP-AT firmware, although you will need to flash it yourself. Please see the [espat driver](https://github.com/tinygo-org/drivers/tree/release/espat). ## Interfaces @@ -136,7 +142,3 @@ Once you have updated your ProductivityOpen P1AM-100 board the first time, after ## Notes You can use the USB port to the ProductivityOpen P1AM-100 as a serial port. `UART0` refers to this connection. - -For information on how to use the built-in NINA-W102 wireless chip with the default firmware, please see the "wifinina" driver in the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/wifinina](https://github.com/tinygo-org/drivers/tree/release/wifinina). - -You can also use the Espressif ESP-AT firmware, although you will need to flash it yourself. Please see the "espat" driver in the TinyGo drivers repository located at [https://github.com/tinygo-org/drivers/tree/release/espat](https://github.com/tinygo-org/drivers/tree/release/espat). diff --git a/content/docs/reference/microcontrollers/particle-argon.md b/content/docs/reference/microcontrollers/particle-argon.md index 20154763..534a90ca 100644 --- a/content/docs/reference/microcontrollers/particle-argon.md +++ b/content/docs/reference/microcontrollers/particle-argon.md @@ -3,7 +3,12 @@ title: "Particle Argon" weight: 3 --- -[The Particle Argon](https://docs.particle.io/datasheets/wi-fi/argon-datasheet/) is a powerful Wi-Fi enabled development board. It is based on the Nordic [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) and ESP32 2.4 GHz Wi-Fi coprocessor. +The [Argon](https://docs.particle.io/datasheets/wi-fi/argon-datasheet/) is a powerful Wi-Fi enabled development board. It is based on the Nordic [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840). + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth +- ESP32 2.4 GHz Wi-Fi coprocessor ## Interfaces diff --git a/content/docs/reference/microcontrollers/particle-boron.md b/content/docs/reference/microcontrollers/particle-boron.md index 8457a6f3..b65d7c95 100644 --- a/content/docs/reference/microcontrollers/particle-boron.md +++ b/content/docs/reference/microcontrollers/particle-boron.md @@ -3,7 +3,12 @@ title: "Particle Boron" weight: 3 --- -[The Particle Boron](https://docs.particle.io/datasheets/cellular/boron-datasheet/) The Boron is a powerful LTE CAT-M1/2G/3G enabled development kit that supports cellular networks and Bluetooth LE (BLE). It is based on the Nordic [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) and u-blox SARA coprocessor. +The [Boron](https://docs.particle.io/datasheets/cellular/boron-datasheet/) is based on the Nordic [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840). + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth +- u-blox SARA coprocessor: LTE CAT-M1/2G/3G, supports cellular networks ## Interfaces @@ -83,5 +88,3 @@ Programs are loaded onto the Particle Boron board using the `openocd` command li ## Notes You can use the USB port to the Particle Boron as a serial port. `UART0` refers to this connection. - -Bluetooth support is in development but not yet completed. diff --git a/content/docs/reference/microcontrollers/particle-xenon.md b/content/docs/reference/microcontrollers/particle-xenon.md index c7b0b1c3..54cb29f3 100644 --- a/content/docs/reference/microcontrollers/particle-xenon.md +++ b/content/docs/reference/microcontrollers/particle-xenon.md @@ -3,7 +3,11 @@ title: "Particle Xenon" weight: 3 --- -[The Particle Xenon](https://docs.particle.io/datasheets/discontinued/xenon-datasheet/) is a low cost mesh-enabled development board. +The [Xenon](https://docs.particle.io/datasheets/discontinued/xenon-datasheet/) is based on the Nordic [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840). + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth ## Interfaces @@ -75,5 +79,3 @@ Programs are loaded onto the Particle Xenon board using the `openocd` command li ## Notes You can use the USB port to the Particle Xenon as a serial port. `UART0` refers to this connection. - -Bluetooth support is in development but not yet completed. diff --git a/content/docs/reference/microcontrollers/pca10031.md b/content/docs/reference/microcontrollers/pca10031.md index 4456da72..4543c75d 100644 --- a/content/docs/reference/microcontrollers/pca10031.md +++ b/content/docs/reference/microcontrollers/pca10031.md @@ -3,7 +3,11 @@ title: "Nordic Semiconductor PCA10031" weight: 3 --- -The [Nordic Semiconductor PCA10031](https://www.nordicsemi.com/eng/Products/nRF51-Dongle) is a low-cost, versatile USB development dongle for wireless applications based on the Nordic Semiconductor [nRF51422](https://www.nordicsemi.com/eng/Products/ANT/nRF51422) chip using the nRF51 series SoC. +The [PCA10031](https://www.nordicsemi.com/eng/Products/nRF51-Dongle) is a low-cost, versatile USB development dongle for wireless applications based on the Nordic Semiconductor [nRF51422](https://www.nordicsemi.com/eng/Products/ANT/nRF51422) SoC. + +## Peripherals and Drivers + +- [nRF51422](https://github.com/tinygo-org/bluetooth) Bluetooth ## Interfaces diff --git a/content/docs/reference/microcontrollers/pca10040.md b/content/docs/reference/microcontrollers/pca10040.md index 4e677279..785af214 100644 --- a/content/docs/reference/microcontrollers/pca10040.md +++ b/content/docs/reference/microcontrollers/pca10040.md @@ -3,7 +3,11 @@ title: "Nordic Semiconductor PCA10040" weight: 3 --- -The [Nordic Semiconductor PCA10040](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52-DK) is a single-board development kit for wireless applications based on the Nordic Semiconductor [nRF52832](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52832) SoC. +The [PCA10040](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52-DK) is a single-board development kit for wireless applications based on the Nordic Semiconductor [nRF52832](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52832) SoC. + +## Peripherals and Drivers + +- [nRF52832](https://github.com/tinygo-org/bluetooth) Bluetooth ## Interfaces diff --git a/content/docs/reference/microcontrollers/pca10056.md b/content/docs/reference/microcontrollers/pca10056.md index 4c800204..25b0c27e 100644 --- a/content/docs/reference/microcontrollers/pca10056.md +++ b/content/docs/reference/microcontrollers/pca10056.md @@ -3,7 +3,11 @@ title: "Nordic Semiconductor PCA10056" weight: 3 --- -The [Nordic Semiconductor PCA10056](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) is a single-board development kit for wireless applications based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) SoC. +The [PCA10056](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) is a single-board development kit for wireless applications based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) SoC. + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth ## Interfaces diff --git a/content/docs/reference/microcontrollers/pca10059.md b/content/docs/reference/microcontrollers/pca10059.md index ad59acd5..3354d8c7 100644 --- a/content/docs/reference/microcontrollers/pca10059.md +++ b/content/docs/reference/microcontrollers/pca10059.md @@ -3,7 +3,11 @@ title: "Nordic Semiconductor PCA10059" weight: 3 --- -The [Nordic Semiconductor PCA10059](https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF52840-Dongle) is a single-board development kit for wireless applications based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) SoC. +The [PCA10059](https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF52840-Dongle) is a single-board development kit for wireless applications based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) SoC. + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth ## Interfaces diff --git a/content/docs/reference/microcontrollers/pinetime-devkit0.md b/content/docs/reference/microcontrollers/pinetime.md similarity index 89% rename from content/docs/reference/microcontrollers/pinetime-devkit0.md rename to content/docs/reference/microcontrollers/pinetime.md index 4bf06c1e..1847269f 100644 --- a/content/docs/reference/microcontrollers/pinetime-devkit0.md +++ b/content/docs/reference/microcontrollers/pinetime.md @@ -1,10 +1,14 @@ --- -title: "PineTime DevKit" +title: "Pine64 PineTime" weight: 3 --- The [PineTime](https://wiki.pine64.org/index.php/PineTime) is a smartwatch by [Pine64](https://www.pine64.org/) that is based on the Nordic Semiconductor [nRF52832](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52832) SoC. As of October 2019, a limited amount has been produced for developers. +## Peripherals and Drivers + +- [nRF52832](https://github.com/tinygo-org/bluetooth) Bluetooth + ## Interfaces | Interface | Hardware Supported | TinyGo Support | @@ -24,7 +28,6 @@ The [PineTime](https://wiki.pine64.org/index.php/PineTime) is a smartwatch by [P | `LED1` | `P0_23` | `LED`, `LCD_BACKLIGHT_HIGH` | | `LED2` | `P0_22` | `LCD_BACKLIGHT_MID` | | `LED3` | `P0_14` | `LCD_BACKLIGHT_LOW` | -| `UART_TX_PIN` | `P0_11` | | | `SPI0_SCK_PIN` | `P0_02` | `LCD_SCK` | | `SPI0_SDO_PIN` | `P0_03` | `LCD_SDI` | | `SPI0_SDI_PIN` | `P0_04` | | @@ -70,7 +73,8 @@ You can find how to install nrfjprog in the [documentation for the pca10040 boar ### Unlock chip using OpenOCD -Recent OpenOCD versions support unlocking/erasing the flash. Unfortunately, it isn't supported by OpenOCD 0.10, which is (as of October 2019) included in most Linux distributions. So you'll have to compile OpenOCD from source and use that. See [this StackOverflow answer](https://stackoverflow.com/questions/52308978/problem-flashing-nrf52-chip-using-openocd#54372481) for more details. +Recent OpenOCD versions support unlocking/erasing the flash. Unfortunately, it isn't supported by OpenOCD 0.10, which is (as of October 2019) included in most Linux distributions. So you'll have to compile OpenOCD from source and use that. +See [this StackOverflow answer](https://stackoverflow.com/questions/52308978/problem-flashing-nrf52-chip-using-openocd#54372481) for more details. After unlocking, you can use a regular OpenOCD version (like 0.10) for flashing. @@ -78,6 +82,6 @@ After unlocking, you can use a regular OpenOCD version (like 0.10) for flashing. See above for how to connect the PineTime to your computer. When it is connected, you can flash programs to it. For example, to blink the LCD backlight: -```sh -tinygo flash -target=pinetime-devkit0 examples/blinky1 +```shell +tinygo flash -target=pinetime examples/blinky1 ``` diff --git a/content/docs/reference/microcontrollers/pybadge.md b/content/docs/reference/microcontrollers/pybadge.md index e35cfa17..5b6ca2d4 100644 --- a/content/docs/reference/microcontrollers/pybadge.md +++ b/content/docs/reference/microcontrollers/pybadge.md @@ -3,9 +3,16 @@ title: "Adafruit PyBadge" weight: 3 --- -The [Adafruit PyBadge](https://www.adafruit.com/product/4200) is a ARM development board based on the Atmel [ATSAMD51J19A](https://www.microchip.com/wwwproducts/en/ATSAMD51J19A) family of SoC. +The [PyBadge](https://www.adafruit.com/product/4200) is a ARM development board based on the Atmel [ATSAMD51J19A](https://www.microchip.com/wwwproducts/en/ATSAMD51J19A) family of SoC. -It has many built-in devices, such as a 1.8" 160x128 Color TFT Display, 8 x buttons, 5 x NeoPixels, a triple-axis accelerometer, a light sensor, and a speaker. The PyBadge uses the ST7735 display, so you may use the tinygo-org st7735 driver. The accelerometer is the LIS3DH so you may use the tinygo lis3dh driver +## Peripherals and Drivers + +- [LIS3DH](https://pkg.go.dev/tinygo.org/x/drivers/lis3dh) IMU chip (acceleration, tap detection, free-fall detection) +- [ST7735](https://pkg.go.dev/tinygo.org/x/drivers/st7735) 1.8" 160x128 Color TFT Display +- [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) 5 x NeoPixels +- 8 x buttons +- Light sensor +- Speaker ## Interfaces @@ -98,10 +105,9 @@ If you have troubles getting your PyBadge board to receive code, try this: - The PyBadge board will appear to your computer like a USB drive. - Now try running the command as above: - -```shell -tinygo flash -target=pybadge [PATH TO YOUR PROGRAM] -``` + ```shell + tinygo flash -target=pybadge [PATH TO YOUR PROGRAM] + ``` Once you have updated your PyBadge board the first time, after that you should be able to flash it entirely from the command line. diff --git a/content/docs/reference/microcontrollers/pygamer.md b/content/docs/reference/microcontrollers/pygamer.md index 94bba029..4a699cf5 100644 --- a/content/docs/reference/microcontrollers/pygamer.md +++ b/content/docs/reference/microcontrollers/pygamer.md @@ -3,9 +3,17 @@ title: "Adafruit PyGamer" weight: 3 --- -The [Adafruit PyGamer](https://www.adafruit.com/product/4242) is a ARM development board based on the Atmel [ATSAMD51J19A](https://www.microchip.com/wwwproducts/en/ATSAMD51J19A) family of SoC. +The [PyGamer](https://www.adafruit.com/product/4242) is a ARM development board based on the Atmel [ATSAMD51J19A](https://www.microchip.com/wwwproducts/en/ATSAMD51J19A) family of SoC. -It has many built-in devices, such as a 1.8" 160x128 Color TFT Display, a dual-potentiometer analog stick, 4 x square-top buttons, 5 x NeoPixel LED, a triple-axis accelerometer, a light sensor, and a speaker. The PyGamer uses the ST7735 display, so you may use the tinygo-org st7735 driver. The accelerometer is the LIS3DH so you may use the tinygo lis3dh driver. +## Peripherals and Drivers + +- [LIS3DH](https://pkg.go.dev/tinygo.org/x/drivers/lis3dh) IMU chip (acceleration, tap detection, free-fall detection) +- [ST7735](https://pkg.go.dev/tinygo.org/x/drivers/st7735) 1.8" 160x128 Color TFT Display +- Dual-potentiometer analog stick +- 4 x square-top buttons +- [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) 5 x NeoPixel LED +- Light sensor +- Speaker ## Interfaces @@ -100,10 +108,9 @@ If you have troubles getting your PyGamer board to receive code, try this: - The PyGamer board will appear to your computer like a USB drive. - Now try running the command as above: - -```shell -tinygo flash -target=pygamer [PATH TO YOUR PROGRAM] -``` + ```shell + tinygo flash -target=pygamer [PATH TO YOUR PROGRAM] + ``` Once you have updated your PyGamer board the first time, after that you should be able to flash it entirely from the command line. diff --git a/content/docs/reference/microcontrollers/pyportal.md b/content/docs/reference/microcontrollers/pyportal.md index 6e7291ee..d37aac61 100644 --- a/content/docs/reference/microcontrollers/pyportal.md +++ b/content/docs/reference/microcontrollers/pyportal.md @@ -3,9 +3,20 @@ title: "Adafruit PyPortal" weight: 3 --- -The [Adafruit PyPortal](https://www.adafruit.com/product/4116) is a ARM board based on the Microchip [ATSAMD51J20A](https://www.microchip.com/wwwproducts/en/ATSAMD51J20A) family of SoC. +The [PyPortal](https://www.adafruit.com/product/4116) is a ARM board based on the Microchip [ATSAMD51J20A](https://www.microchip.com/wwwproducts/en/ATSAMD51J20A) family of SoC. -The PyPortal also has an Espressif ESP32 Wi-Fi coprocessor with TLS/SSL support built-in. PyPortal has a 3.2″ 320 x 240 color TFT with resistive touch screen. PyPortal includes: speaker, light sensor, temperature sensor, NeoPixel, microSD card slot, 8MB flash, plug-in ports for I2C and 2 analog/digital pins, +## Peripherals and Drivers + +- [LIS3DH](https://pkg.go.dev/tinygo.org/x/drivers/lis3dh) IMU chip (acceleration, tap detection, free-fall detection) +- 3.2″ 320 x 240 color TFT with resistive touch screen +- [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) 5 x NeoPixels +- 8 x buttons +- Light sensor +- Temperature sensor +- Speaker +- ESP32 Wi-Fi coprocessor with TLS/SSL support built-in +- [SD-Card](https://pkg.go.dev/tinygo.org/x/drivers/sdcard) slot +- 8MB flash ## Interfaces @@ -100,10 +111,9 @@ If you have troubles getting your PyPortal board to receive code, try this: - The PyPortal board will appear to your computer like a USB drive. - Now try running the command as above: - -```shell -tinygo flash -target=pyportal [PATH TO YOUR PROGRAM] -``` + ```shell + tinygo flash -target=pyportal [PATH TO YOUR PROGRAM] + ``` Once you have updated your PyPortal board the first time, after that you should be able to flash it entirely from the command line. diff --git a/content/docs/reference/microcontrollers/qtpy-esp32c3.md b/content/docs/reference/microcontrollers/qtpy-esp32c3.md new file mode 100644 index 00000000..afe9859d --- /dev/null +++ b/content/docs/reference/microcontrollers/qtpy-esp32c3.md @@ -0,0 +1,65 @@ +--- +title: "Adafruit QT Py ESP32-C3" +weight: 3 +--- + +The [QT Py ESP32-C3](https://www.adafruit.com/product/5405) is a development board based on the [Espressif ESP32-C3](https://www.espressif.com/en/products/socs/esp32-c3). + +## Peripherals and Drivers + +A powerful chip that is used on many different boards mostly because of the built-in radio that can be used for WiFi or Bluetooth wireless connections. + +## Interfaces + +| Interface | Hardware Supported | TinyGo Support | +| --------- | ------------- | ----- | +| GPIO | YES | YES | +| UART | YES | YES | +| SPI | YES | YES | +| I2C | YES | YES | +| ADC | YES | Not yet | +| PWM | YES | Not yet | +| USBDevice | YES | Not yet | +| WiFi | YES | Not yet | +| Bluetooth | YES | Not yet | + +## Pins + +| Pin | Hardware pin | Alternative names | +| ----------------- | ------------ | ----------------- | +| `D0` | `GPIO4` | `A0` | +| `D1` | `GPIO3` | `A1` | +| `D2` | `GPIO1` | `A2` | +| `D3` | `GPIO0` | `A3` | +| `RX_PIN` | `GPIO20` | `UART_RX_PIN` | +| `TX_PIN` | `GPIO21` | `UART_TX_PIN` | +| `SDA_PIN` | `GPIO5` | `I2C0_SDA_PIN` | +| `SCL_PIN` | `GPIO6` | `I2C0_SCL_PIN` | +| `SCK_PIN` | `GPIO10` | `SPI_SCK_PIN` | +| `MI_PIN` | `GPIO8` | `SPI_SDI_PIN` | +| `MO_PIN` | `GPIO7` | `SPI_SDO_PIN` | +| `NEOPIXEL` | `GPIO2` | `WS2812` | +| `BUTTON` | `GPIO9` | | + +## Machine Package Docs + +[Documentation for the machine package for the QT Py ESP32-C3](../machine/qtpy-esp32c3) + +## Flashing + +### CLI Flashing + +In addition, you must install the `esptool` flashing tool: + +https://github.com/espressif/esptool#easy-installation + +Now you should be able to flash your board as follows: + +- Plug your ESP32-C3 board into your computer's USB port. +- Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32-C3 with the serial example: + + ```shell + tinygo flash -target=xiao-esp32c3 examples/serial + ``` + +- The ESP32-C3 board should restart and then begin running your program. diff --git a/content/docs/reference/microcontrollers/qtpy-rp2040.md b/content/docs/reference/microcontrollers/qtpy-rp2040.md index eabc9316..adda0434 100644 --- a/content/docs/reference/microcontrollers/qtpy-rp2040.md +++ b/content/docs/reference/microcontrollers/qtpy-rp2040.md @@ -3,7 +3,7 @@ title: "Adafruit QT Py RP2040" weight: 3 --- -The [Adafruit QT Py RP2040](https://www.adafruit.com/product/4900) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. +The [QT Py RP2040](https://www.adafruit.com/product/4900) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. ## Interfaces diff --git a/content/docs/reference/microcontrollers/qtpy.md b/content/docs/reference/microcontrollers/qtpy.md index 03567b99..3388de29 100644 --- a/content/docs/reference/microcontrollers/qtpy.md +++ b/content/docs/reference/microcontrollers/qtpy.md @@ -1,9 +1,9 @@ --- -title: "Adafruit Qt Py" +title: "Adafruit QT Py" weight: 3 --- -The [Adafruit QtPy](https://www.adafruit.com/product/4600) is a tiny ARM development board based on the Atmel [ATSAMD21E18](https://www.microchip.com/wwwproducts/en/ATSAMD21E18) family of SoC. +The [QT Py](https://www.adafruit.com/product/4600) is a tiny ARM development board based on the Atmel [ATSAMD21E18](https://www.microchip.com/wwwproducts/en/ATSAMD21E18) family of SoC. ## Interfaces diff --git a/content/docs/reference/microcontrollers/reelboard.md b/content/docs/reference/microcontrollers/reelboard.md index d65f38c7..3c095d1e 100644 --- a/content/docs/reference/microcontrollers/reelboard.md +++ b/content/docs/reference/microcontrollers/reelboard.md @@ -5,7 +5,14 @@ weight: 3 The [reel board](https://www.phytec.eu/product-eu/internet-of-things/reelboard/) is an evaluation board based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) SoC. -It is equipped with an Electrophoretic (electronic ink) Display (EPD), along with temperature, humidity, light, and accelerometer sensors, and Bluetooth connectivity. +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth +- Electrophoretic (electronic ink) Display (EPD) +- temperature sensor +- humidity sensor +- light sensor +- accelerometer ## Interfaces @@ -70,5 +77,3 @@ Programs can also be loaded onto the reelboard using the `openocd` command line - Plug your reelboard into your computer's USB port. - Build and flash your TinyGo program using `tinygo flash -target=reelboard` - -Bluetooth support is now available for reelboard. See https://github.com/tinygo-org/bluetooth for more information. diff --git a/content/docs/reference/microcontrollers/stm32f4disco.md b/content/docs/reference/microcontrollers/stm32f4disco.md index 05723f1b..4c886956 100644 --- a/content/docs/reference/microcontrollers/stm32f4disco.md +++ b/content/docs/reference/microcontrollers/stm32f4disco.md @@ -1,12 +1,17 @@ --- -title: 'ST Micro STM32F407 "Discovery"' +title: 'ST Micro STM32F4 Discovery' weight: 3 --- The [STM32F4 Discovery](https://www.st.com/en/evaluation-tools/stm32f4discovery.html) is an ARM development board based on the ST Micro [STM32F407](https://www.st.com/resource/en/datasheet/stm32f407vg.pdf) SoC. -It has an onboard LIS302DL or LIS3DSH accelerometer, MP45DT02 MEMS digital microphone, an -CS43L22 audio DAC, 2 user buttons, and 4 user LEDs. +## Peripherals and Drivers + +- LIS302DL or LIS3DSH accelerometer +- MP45DT02 MEMS digital microphone +- CS43L22 audio DAC +- 2 user buttons +- 4 user LEDs ## Interfaces diff --git a/content/docs/reference/microcontrollers/swan.md b/content/docs/reference/microcontrollers/swan.md index 912070f4..f0855df7 100644 --- a/content/docs/reference/microcontrollers/swan.md +++ b/content/docs/reference/microcontrollers/swan.md @@ -3,7 +3,9 @@ title: "Blues Wireless Swan" weight: 3 --- -The [Swan](https://blues.io/products/swan/) is an ARM development board based on the ST Micro [stm32l4r5zi](https://www.st.com/en/microcontrollers-microprocessors/stm32l4r5zi.html) SoC. +The [Wireless Swan](https://blues.io/products/swan/) is an ARM development board based on the ST Micro [stm32l4r5zi](https://www.st.com/en/microcontrollers-microprocessors/stm32l4r5zi.html) SoC. + +## Peripherals and Drivers The Swan has a user button and an LED, LiPo charging and USB. diff --git a/content/docs/reference/microcontrollers/teensy36.md b/content/docs/reference/microcontrollers/teensy36.md index 170fc9fe..52590f0d 100644 --- a/content/docs/reference/microcontrollers/teensy36.md +++ b/content/docs/reference/microcontrollers/teensy36.md @@ -3,7 +3,7 @@ title: "PJRC Teensy 3.6" weight: 3 --- -The [PJRC Teensy 3.6](https://www.pjrc.com/store/teensy36.html) is a small ARM development board based on the NXP [MK66FX1M0VMD18](https://www.nxp.com/docs/en/data-sheet/K66P144M180SF5V2.pdf) 32-bit 180 MHz ARM Cortex-M4. +The [Teensy 3.6](https://www.pjrc.com/store/teensy36.html) is a small ARM development board based on the NXP [MK66FX1M0VMD18](https://www.nxp.com/docs/en/data-sheet/K66P144M180SF5V2.pdf) 32-bit 180 MHz ARM Cortex-M4. ## Interfaces @@ -94,7 +94,7 @@ The [PJRC Teensy 3.6](https://www.pjrc.com/store/teensy36.html) is a small ARM d ### teensy_loader_cli -In order to flash your TinyGo programs onto the Teensy 3.6 board, you will need to install the `teensy_loader_cli` (https://github.com/PaulStoffregen/teensy_loader_cli) on your machine. +In order to flash your TinyGo programs onto the Teensy 3.6 board, you will need to install the [teensy_loader_cli](https://github.com/PaulStoffregen/teensy_loader_cli) on your machine. ### CLI Flashing diff --git a/content/docs/reference/microcontrollers/teensy40.md b/content/docs/reference/microcontrollers/teensy40.md index dc5a3c5c..29e78b94 100644 --- a/content/docs/reference/microcontrollers/teensy40.md +++ b/content/docs/reference/microcontrollers/teensy40.md @@ -3,7 +3,7 @@ title: "PJRC Teensy 4.0" weight: 3 --- -The [PJRC Teensy 4.0](https://www.pjrc.com/store/teensy40.html) is a small ARM development board based on the NXP [iMXRT1062](https://www.nxp.com/docs/en/nxp/data-sheets/IMXRT1060CEC.pdf) 32-bit 600 MHz ARM Cortex-M7. +The [Teensy 4.0](https://www.pjrc.com/store/teensy40.html) is a small ARM development board based on the NXP [iMXRT1062](https://www.nxp.com/docs/en/nxp/data-sheets/IMXRT1060CEC.pdf) 32-bit 600 MHz ARM Cortex-M7. ## Interfaces @@ -70,7 +70,7 @@ The [PJRC Teensy 4.0](https://www.pjrc.com/store/teensy40.html) is a small ARM d ### teensy_loader_cli -In order to flash your TinyGo programs onto the Teensy 4.0 board, you will need to install the `teensy_loader_cli` (https://github.com/PaulStoffregen/teensy_loader_cli) on your machine. +In order to flash your TinyGo programs onto the Teensy 4.0 board, you will need to install the [teensy_loader_cli](https://github.com/PaulStoffregen/teensy_loader_cli) on your machine. ### CLI Flashing diff --git a/content/docs/reference/microcontrollers/thingplus-rp2040.md b/content/docs/reference/microcontrollers/thingplus-rp2040.md index f0c2eb0e..a04d8c1c 100644 --- a/content/docs/reference/microcontrollers/thingplus-rp2040.md +++ b/content/docs/reference/microcontrollers/thingplus-rp2040.md @@ -3,11 +3,12 @@ title: "Sparkfun Thing Plus RP2040" weight: 3 --- -The [Sparkfun Thing Plus RP2040](https://www.sparkfun.com/products/17745) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. +The [Thing Plus RP2040](https://www.sparkfun.com/products/17745) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. -Peripherals: -- ws2812 Neopixel -- sdcard +## Peripherals and Drivers + +- [WS2812](https://pkg.go.dev/tinygo.org/x/drivers/ws2812) Neopixel (built-in) +- [SD-Card](https://pkg.go.dev/tinygo.org/x/drivers/sdcard) ## Interfaces @@ -80,5 +81,3 @@ Any troubleshooting tips go here. ## Notes You can use the USB port to the Thing Plus RP2040 as a serial port. - -The Neopixel LED and the SD Card are supported by [tinygo drivers](https://github.com/tinygo-org/drivers) diff --git a/content/docs/reference/microcontrollers/trinket-m0.md b/content/docs/reference/microcontrollers/trinket-m0.md index 4ac18af7..9f299ca8 100644 --- a/content/docs/reference/microcontrollers/trinket-m0.md +++ b/content/docs/reference/microcontrollers/trinket-m0.md @@ -3,7 +3,11 @@ title: "Adafruit Trinket M0" weight: 3 --- -The [Adafruit Trinket M0](https://www.adafruit.com/product/3500) is a tiny ARM development board based on the Atmel [ATSAMD21E18](https://www.microchip.com/wwwproducts/en/ATSAMD21E18) family of SoC. +The [Trinket M0](https://www.adafruit.com/product/3500) is a tiny ARM development board based on the Atmel [ATSAMD21E18](https://www.microchip.com/wwwproducts/en/ATSAMD21E18) family of SoC. + +## Peripherals and Drivers + +The DotStar LED on the Trinket M0 can be accessed using the [APA102](https://pkg.go.dev/tinygo.org/x/drivers/apa102) driver via a software SPI on the `PA01` and `PA00` pins ## Interfaces @@ -68,5 +72,3 @@ Once you have updated your Trinket M0 board the first time, after that you shoul ## Notes You can use the USB port to the Trinket M0 as a serial port. `UART0` refers to this connection. - -The DotStar LED on the Trinket M0 can be accessed using the [APA102](https://pkg.go.dev/tinygo.org/x/drivers/apa102) driver via a software SPI on the `PA01` and `PA00` pins diff --git a/content/docs/reference/microcontrollers/trinkey-qt2040.md b/content/docs/reference/microcontrollers/trinkey-qt2040.md index 07ab5782..70b2fab3 100644 --- a/content/docs/reference/microcontrollers/trinkey-qt2040.md +++ b/content/docs/reference/microcontrollers/trinkey-qt2040.md @@ -3,7 +3,7 @@ title: "Adafruit Trinkey QT2040" weight: 3 --- -The [Adafruit Trinkey QT2040](https://www.adafruit.com/product/5056) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. +The [Trinkey QT2040](https://www.adafruit.com/product/5056) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. ## Interfaces diff --git a/content/docs/reference/microcontrollers/tufty2040.md b/content/docs/reference/microcontrollers/tufty2040.md index 78526186..80d56187 100644 --- a/content/docs/reference/microcontrollers/tufty2040.md +++ b/content/docs/reference/microcontrollers/tufty2040.md @@ -3,7 +3,7 @@ title: "Pimoroni Tufty2040" weight: 3 --- -The [Pimoroni Tufty2040](https://shop.pimoroni.com/products/tufty-2040) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. +The [Tufty2040](https://shop.pimoroni.com/products/tufty-2040) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. ## Interfaces diff --git a/content/docs/reference/microcontrollers/waveshare-rp2040-zero.md b/content/docs/reference/microcontrollers/waveshare-rp2040-zero.md index 1147e3bb..d4bb2c09 100644 --- a/content/docs/reference/microcontrollers/waveshare-rp2040-zero.md +++ b/content/docs/reference/microcontrollers/waveshare-rp2040-zero.md @@ -3,7 +3,7 @@ title: "Waveshare RP2040-Zero" weight: 3 --- -The [Waveshare RP2040-Zero](https://www.waveshare.com/wiki/RP2040-Zero) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. +The [RP2040-Zero](https://www.waveshare.com/wiki/RP2040-Zero) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. ## Interfaces diff --git a/content/docs/reference/microcontrollers/wioterminal.md b/content/docs/reference/microcontrollers/wioterminal.md index bd5c557b..a4095510 100644 --- a/content/docs/reference/microcontrollers/wioterminal.md +++ b/content/docs/reference/microcontrollers/wioterminal.md @@ -3,7 +3,18 @@ title: "Seeed Wio Terminal" weight: 3 --- -The [Seeed Wio Terminal](https://www.seeedstudio.com/Wio-Terminal-p-4509.html) is a tiny ARM development board based on the Atmel [ATSAMD51P20](https://www.microchip.com/wwwproducts/en/ATSAMD51P20A) family of SoC. +The [Wio Terminal](https://www.seeedstudio.com/Wio-Terminal-p-4509.html) is a tiny ARM development board based on the Atmel [ATSAMD51P20](https://www.microchip.com/wwwproducts/en/ATSAMD51P20A) family of SoC. + +## Peripherals and Drivers + +- RTL8720DN: Bluetooth and Wi-Fi Wireless +- 2.4” LCD Screen +- LIS3DHTR: IMU +- Microphone +- Buzzer +- [SD-Card](https://pkg.go.dev/tinygo.org/x/drivers/sdcard) slot +- Light sensor +- Infrared emitter(940nm) ## Interfaces @@ -142,10 +153,9 @@ If you have troubles getting your Wio Terminal board to receive code, try this: - The Wio Terminal board will appear to your computer like a USB drive. - Now try running the command as above: - -```shell -tinygo flash -target=wioterminal [PATH TO YOUR PROGRAM] -``` + ```shell + tinygo flash -target=wioterminal [PATH TO YOUR PROGRAM] + ``` Once you have updated your Wio Terminal board the first time, after that you should be able to flash it entirely from the command line. diff --git a/content/docs/reference/microcontrollers/xiao-ble.md b/content/docs/reference/microcontrollers/xiao-ble.md index 5f52a5d2..1686148d 100644 --- a/content/docs/reference/microcontrollers/xiao-ble.md +++ b/content/docs/reference/microcontrollers/xiao-ble.md @@ -3,7 +3,11 @@ title: "Seeed XIAO BLE" weight: 3 --- -The [Seeed XIAO BLE](https://www.seeedstudio.com/Seeed-XIAO-BLE-nRF52840-p-5201.html) is a tiny ARM development board based on the Nordic Semiconductor [nrf52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. +The [XIAO BLE](https://www.seeedstudio.com/Seeed-XIAO-BLE-nRF52840-p-5201.html) is a tiny ARM development board based on the Nordic Semiconductor [nRF52840](https://www.nordicsemi.com/eng/Products/nRF52840) processor. + +## Peripherals and Drivers + +- [nRF52840](https://github.com/tinygo-org/bluetooth) Bluetooth ## Interfaces @@ -73,4 +77,3 @@ Add troubleshooting tips here. ## Notes You can use the USB port to the XIAO BLE as a serial port. `UART0` refers to this connection. - diff --git a/content/docs/reference/microcontrollers/xiao-esp32c3.md b/content/docs/reference/microcontrollers/xiao-esp32c3.md new file mode 100644 index 00000000..ab56c46f --- /dev/null +++ b/content/docs/reference/microcontrollers/xiao-esp32c3.md @@ -0,0 +1,63 @@ +--- +title: "Seeed XIAO ESP32 C3" +weight: 3 +--- + +The [XIAO ESP32 C3](https://www.seeedstudio.com/Seeed-XIAO-ESP32C3-p-5431.html) is a development board based on the [Espressif ESP32-C3](https://www.espressif.com/en/products/socs/esp32-c3). + +## Peripherals and Drivers + +A powerful chip that is used on many different boards mostly because of the built-in radio that can be used for WiFi or Bluetooth wireless connections. + +## Interfaces + +| Interface | Hardware Supported | TinyGo Support | +| --------- | ------------- | ----- | +| GPIO | YES | YES | +| UART | YES | YES | +| SPI | YES | YES | +| I2C | YES | YES | +| ADC | YES | Not yet | +| PWM | YES | Not yet | +| USBDevice | YES | Not yet | +| WiFi | YES | Not yet | +| Bluetooth | YES | Not yet | + +## Pins + +| Pin | Hardware pin | Alternative names | +| ----------------- | ------------ | ----------------- | +| `D0` | `GPIO2` | `A0` | +| `D1` | `GPIO3` | `A1` | +| `D2` | `GPIO4` | `A2` | +| `D3` | `GPIO5` | `A3` | +| `D4` | `GPIO6` | `SDA_PIN` | +| `D5` | `GPIO7` | `SCL_PIN` | +| `D6` | `GPIO21` | `UART_TX_PIN` | +| `D7` | `GPIO20` | `UART_RX_PIN` | +| `D8` | `GPIO8` | `SPI_SCK_PIN` | +| `D9` | `GPIO9` | `SPI_SDI_PIN` | +| `D10` | `GPIO10` | `SPI_SDO_PIN` | + +## Machine Package Docs + +[Documentation for the machine package for the XIAO ESP32 C3](../machine/xiao-esp32c3) + +## Flashing + +### CLI Flashing + +In addition, you must install the `esptool` flashing tool: + +https://github.com/espressif/esptool#easy-installation + +Now you should be able to flash your board as follows: + +- Plug your ESP32-C3 board into your computer's USB port. +- Build and flash your TinyGo code using the `tinygo flash` command. This command flashes the ESP32-C3 with the serial example: + + ```shell + tinygo flash -target=xiao-esp32c3 examples/serial + ``` + +- The ESP32-C3 board should restart and then begin running your program. diff --git a/content/docs/reference/microcontrollers/xiao-rp2040.md b/content/docs/reference/microcontrollers/xiao-rp2040.md index 1883e1e8..94fd80e3 100644 --- a/content/docs/reference/microcontrollers/xiao-rp2040.md +++ b/content/docs/reference/microcontrollers/xiao-rp2040.md @@ -3,7 +3,7 @@ title: "Seeed XIAO RP2040" weight: 3 --- -The [Seeed XIAO RP2040](https://www.seeedstudio.com/XIAO-RP2040-v1-0-p-5026.html) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. +The [XIAO RP2040](https://www.seeedstudio.com/XIAO-RP2040-v1-0-p-5026.html) is a tiny development board based on the Raspberry Pi [RP2040](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf) microcontroller. ## Interfaces diff --git a/content/docs/reference/microcontrollers/xiao.md b/content/docs/reference/microcontrollers/xiao.md index 33bc5f55..084557ed 100644 --- a/content/docs/reference/microcontrollers/xiao.md +++ b/content/docs/reference/microcontrollers/xiao.md @@ -3,7 +3,7 @@ title: "Seeed Seeeduino XIAO" weight: 3 --- -The [Seeed Seeeduino XIAO](https://www.seeedstudio.com/Seeeduino-XIAO-Arduino-Microcontroller-SAMD21-Cortex-M0+-p-4426.html) is a tiny ARM development board based on the Atmel [ATSAMD21G18](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of SoC. +The [Seeeduino XIAO](https://www.seeedstudio.com/Seeeduino-XIAO-Arduino-Microcontroller-SAMD21-Cortex-M0+-p-4426.html) is a tiny ARM development board based on the Atmel [ATSAMD21G18](https://www.microchip.com/wwwproducts/en/ATSAMD21G18) family of SoC. ## Interfaces @@ -67,14 +67,12 @@ If you have troubles getting your XIAO board to receive code, try this: - The XIAO board will appear to your computer like a USB drive. - Now try running the command as above: - -```shell -tinygo flash -target=xiao [PATH TO YOUR PROGRAM] -``` + ```shell + tinygo flash -target=xiao [PATH TO YOUR PROGRAM] + ``` Once you have updated your XIAO board the first time, after that you should be able to flash it entirely from the command line. ## Notes You can use the USB port to the XIAO as a serial port. `UART0` refers to this connection. - diff --git a/doc-gen/Makefile b/doc-gen/Makefile index 2842e8d7..3fc32146 100644 --- a/doc-gen/Makefile +++ b/doc-gen/Makefile @@ -1,2 +1,17 @@ all: - go run . `tinygo targets` + go run . --machine --interfaces --pins --matrix `tinygo targets` + +machine: + go run . --machine `tinygo targets` + +interfaces: + go run . --interfaces `tinygo targets` + +pins: + go run . --pins `tinygo targets` + +matrix: + go run . --matrix `tinygo targets` + +help: + go run . --help diff --git a/doc-gen/README.md b/doc-gen/README.md index a0586baf..a4fc7801 100644 --- a/doc-gen/README.md +++ b/doc-gen/README.md @@ -1,5 +1,47 @@ # Generate documentation for the machine package -To re-generate the documentation, simply run make: +To re-generate the complete documentation, tinygo needs to be [installed](https://tinygo.org/getting-started/install/), than simply run make: - make +`make` + +For more specific document updates, run: + +`make machine`, `make interfaces`, `make pins`, `make matrix` + +or for help: + +`make help` + +## Development + +### Markdown Parser + +Existing documents can be parsed "manually" by finding the section with "strings.Index", finding the block to replace +by text search and replacing the block with a new content by string concatenation. A more powerful way is to use AST +based parsing and rendering of the markdown document. + +Some existing parsers, see also [commonmark implementations](https://github.com/commonmark/commonmark-spec/wiki/List-of-CommonMark-Implementations): + +* , since v2 there is a separate Parse() method, but maybe dead +* , seems small and basic, separate parse and render methods +* , one successor of "blackfriday", separate parser, nice [description](https://blog.kowalczyk.info/article/cxn3/advanced-markdown-processing-in-go.html) good examples to modify AST +* , focused on HTML render, most powerful, could not get it to work yet for modifying AST content + +Some existing renderer: + +* , fluent builder +* , for gomarkdown AST, +* , for goldmark AST, with table support +* , for goldmark AST, contains nice examples for transform + +Some tools to manipulate known AST formats: + +* non found yet written in go, so fluent builder can be a starting point + +We use [goldmark-markdown](https://pkg.go.dev/github.com/teekennedy/goldmark-markdown) for creation of hardware-matrix page. Unfortunately "KindTable" is currently not supported by the [renderer](https://github.com/teekennedy/goldmark-markdown/issues/19), so the site will be created by "text/template". + +### Debugging + +Each target can be processed separately for the update of the specific document part, e.g.: + +`go run . --pins arduino-mega1280` diff --git a/doc-gen/cmd/root.go b/doc-gen/cmd/root.go new file mode 100644 index 00000000..0bbdca8c --- /dev/null +++ b/doc-gen/cmd/root.go @@ -0,0 +1,247 @@ +package cmd + +import ( + "fmt" + "log" + "os" + "path/filepath" + "sort" + "strings" + + "github.com/tinygo-org/tinygo-site/doc-gen/internal/boarddoc" + "github.com/tinygo-org/tinygo-site/doc-gen/internal/hardwarematrix" + "github.com/tinygo-org/tinygo-site/doc-gen/internal/machinepackagedoc" + "github.com/tinygo-org/tinygo-site/doc-gen/internal/targetinfo" +) + +var controllerDocBaseDir = filepath.Join("..", "content", "docs", "reference", "microcontrollers") + +type documentStatus int + +const ( + documentFound documentStatus = iota + 1 + missingDocOk + missingDocButShouldHave + missingDoc + canProcessed + finishedWithoutTargetOk + finishedOk +) + +type collection struct { + target string + controllerDocPath string + docStatus documentStatus + errors []error + matrixRow *hardwarematrix.RowInfo +} + +// this targets are virtual targets or common targets (chips) used as reference (inherits) in documented targets +var targetsKnownToSkip = map[string]struct{}{"atmega1284p": {}, "attiny1616": {}, "clue-alpha": {}, "cortex-m-qemu": {}, + "esp32": {}, "esp32c3": {}, "esp8266": {}, "riscv-qemu": {}, "simavr": {}, "wasi": {}, "wasm": {}} + +// this targets are known to skip since last run, but are able to be documented +// TODO: validate this list +var targetsKnownToSkipAndShouldBeDocumented = map[string]struct{}{"bluemicro840": {}, "esp32-c3-devkit-rust-1": {}, + "feather-m0-express": {}} + +func Execute(targets []string, createMachineDoc, updateBoardInterfaces, updateBoardPins, createHardwareMatrix bool) { + // collect + collector := collectFiles(targets) + + // update documents + for target, co := range collector { + if co.docStatus != canProcessed && co.docStatus != documentFound { + continue + } + + if co.docStatus == canProcessed || createHardwareMatrix { + fmt.Printf("Processing '%s', please be patient\n", target) + } + + if co.docStatus == canProcessed { + if createMachineDoc || updateBoardInterfaces || updateBoardPins { + fmt.Println(" Generating Board documentation...") + machineDocPath := filepath.Join(controllerDocBaseDir, "machine", target+".md") + if err := updateMicrocontrollerDocumentation(target, machineDocPath, co.controllerDocPath, + createMachineDoc, updateBoardInterfaces, updateBoardPins); err != nil { + fmt.Fprintln(os.Stderr, " skipping: because error\t\t", err) + co.errors = append(co.errors, err) + } + } + } + + if createHardwareMatrix { + fmt.Println(" Prepare hardware matrix...") + matrixRow, err := hardwarematrix.ParseFeatureMap(co.controllerDocPath) + if err != nil { + fmt.Fprintln(os.Stderr, " skipping: because error\t\t", err) + co.errors = append(co.errors, err) + continue + } + + co.matrixRow = matrixRow + } + + if co.docStatus == documentFound { + co.docStatus = finishedWithoutTargetOk + continue + } + co.docStatus = finishedOk + } + + if createHardwareMatrix { + fmt.Println("\nUpdate hardware matrix...") + hwmatrixDocPath := filepath.Join("..", "content", "docs", "reference", "hardware-matrix.md") + if err := updateHardwareMatrix(hwmatrixDocPath, collector); err != nil { + fmt.Fprintln(os.Stderr, " skipping: because error\t\t", err) + } + } + + // summary + countErrors := printSummary(collector) + + if countErrors > 0 { + os.Exit(1) + } + + os.Exit(0) +} + +func printSummary(collector map[string]*collection) int { + // prepare the user output + var countMissingDocsOk, countErrors, countFinishedOk int + var targetsWithMissingDoc, targetsWithMissingDocButShouldHave []string + var docWithMissingTarget []string + for target, co := range collector { + switch co.docStatus { + case documentFound, finishedWithoutTargetOk: + docWithMissingTarget = append(docWithMissingTarget, co.controllerDocPath) + case missingDocOk: + countMissingDocsOk++ + case missingDocButShouldHave: + targetsWithMissingDocButShouldHave = append(targetsWithMissingDocButShouldHave, target) + case missingDoc: + targetsWithMissingDoc = append(targetsWithMissingDoc, target) + } + + countErrors += len(co.errors) + + if co.docStatus == finishedOk { + countFinishedOk++ + } + } + + // show the user output + fmt.Println("\n+++ results +++") + fmt.Printf("%d\tdocuments found\n", len(collector)) + fmt.Printf("%d\ttargets known for missing document\n", countMissingDocsOk) + fmt.Printf("%d\ttargets with missing documents\n", len(targetsWithMissingDoc)) + fmt.Printf("%d\ttargets with missing documents but should have one\n", len(targetsWithMissingDocButShouldHave)) + fmt.Printf("%d\ttargets with errors\n", countErrors) + fmt.Printf("%d\ttargets finished successfully\n", countFinishedOk) + fmt.Printf("%d\tpossible orphaned documents\n", len(docWithMissingTarget)) + if len(targetsWithMissingDoc) > 0 { + fmt.Println("\n+++ a missing document is unexpected for this targets +++") + sort.Strings(targetsWithMissingDoc) + fmt.Println(strings.Join(targetsWithMissingDoc, ", ")) + } + + if len(docWithMissingTarget) > 0 { + fmt.Println("\n+++ orphaned documents without target +++") + sort.Strings(docWithMissingTarget) + fmt.Println(strings.Join(docWithMissingTarget, ", ")) + } + + return countErrors +} + +func collectFiles(targets []string) map[string]*collection { + // collect values for processing and statistic, the key is the target + collector := make(map[string]*collection) + + // find all relevant documents in the controller folder + entries, err := os.ReadDir(controllerDocBaseDir) + if err != nil { + log.Fatal(err) + } + + // collect all existing files + for _, entry := range entries { + name := entry.Name() + extension := filepath.Ext(name) + if entry.IsDir() || strings.HasPrefix(name, "_") || extension != ".md" { + continue + } + + target := strings.TrimSuffix(name, extension) + co := collection{docStatus: documentFound, controllerDocPath: filepath.Join(controllerDocBaseDir, name)} + collector[target] = &co + } + + for _, target := range targets { + co, ok := collector[target] + if !ok { + // document not exist + co := collection{docStatus: missingDoc} + collector[target] = &co + + if _, ok := targetsKnownToSkip[target]; ok { + // this is not an error, so we skip it silently + co.docStatus = missingDocOk + continue + } + + if _, ok := targetsKnownToSkipAndShouldBeDocumented[target]; ok { + // this targets are known as missing, so we skip it here silently, but those are open TODO's + co.docStatus = missingDocButShouldHave + continue + } + + fmt.Fprintln(os.Stderr, "Skipping: because missing microcontroller markdown document\t", target) + continue + } + + co.docStatus = canProcessed + } + + return collector +} + +func updateMicrocontrollerDocumentation(target, machineDocPath, controllerDocPath string, + createMachineDoc, updateBoardInterfaces, updateBoardPins bool) error { + ti, err := targetinfo.Create(target) + if err != nil { + return fmt.Errorf("target info can not be created: %v", err) + } + + if createMachineDoc { + err = machinepackagedoc.CreateNew(machineDocPath, target, ti.Pkg) + if err != nil { + return fmt.Errorf("error on write machine package doc: %v", err) + } + } + + errors := boarddoc.Update(controllerDocPath, ti, updateBoardInterfaces, updateBoardPins) + if len(errors) > 0 { + return fmt.Errorf("error on update board documentation: %v", errors) + } + + return nil +} + +func updateHardwareMatrix(hwmatrixDocPath string, collector map[string]*collection) error { + var matrixRows []*hardwarematrix.RowInfo + for _, co := range collector { + if co.matrixRow == nil || co.matrixRow.Features == nil { + continue + } + matrixRows = append(matrixRows, co.matrixRow) + } + + if err := hardwarematrix.Create(hwmatrixDocPath, matrixRows); err != nil { + return fmt.Errorf("hardware matrix can not be created: %v", err) + } + + return nil +} diff --git a/doc-gen/doc-gen.go b/doc-gen/doc-gen.go new file mode 100644 index 00000000..192f5dee --- /dev/null +++ b/doc-gen/doc-gen.go @@ -0,0 +1,24 @@ +package main + +import ( + "flag" + "fmt" + + "github.com/tinygo-org/tinygo-site/doc-gen/cmd" +) + +// main just calls the Execute function +func main() { + + createMachineDoc := flag.Bool("machine", false, "re-create machine package documentation for the given targets") + updateBoardInterfaces := flag.Bool("interfaces", false, "update the Interfaces table for the given targets") + updateBoardPins := flag.Bool("pins", false, "update the Pins table for the given targets") + createHardwareMatrix := flag.Bool("matrix", false, "re-create the hardware matrix document") + flag.Parse() + + // get the targets from the list of command line options + targets := flag.Args() + fmt.Printf("Targets: %+q\n", targets) + + cmd.Execute(targets, *createMachineDoc, *updateBoardInterfaces, *updateBoardPins, *createHardwareMatrix) +} diff --git a/doc-gen/go.mod b/doc-gen/go.mod index bed00ace..06a0f353 100644 --- a/doc-gen/go.mod +++ b/doc-gen/go.mod @@ -2,4 +2,7 @@ module github.com/tinygo-org/tinygo-site/doc-gen go 1.13 -require golang.org/x/tools v0.0.0-20201121010211-780cb80bd7fb +require ( + github.com/yuin/goldmark v1.4.11 + golang.org/x/tools v0.0.0-20201121010211-780cb80bd7fb +) diff --git a/doc-gen/go.sum b/doc-gen/go.sum index c5564f97..596d423c 100644 --- a/doc-gen/go.sum +++ b/doc-gen/go.sum @@ -1,4 +1,6 @@ github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= +github.com/yuin/goldmark v1.4.11 h1:i45YIzqLnUc2tGaTlJCyUxSG8TvgyGqhqOZOUKIjJ6w= +github.com/yuin/goldmark v1.4.11/go.mod h1:rmuwmfZ0+bvzB24eSC//bk1R1Zp3hM0OXYv/G2LIilg= golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI= golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= diff --git a/doc-gen/internal/boarddoc/boarddoc.go b/doc-gen/internal/boarddoc/boarddoc.go new file mode 100644 index 00000000..0d115add --- /dev/null +++ b/doc-gen/internal/boarddoc/boarddoc.go @@ -0,0 +1,168 @@ +package boarddoc + +import ( + "fmt" + "os" + "strings" + + "github.com/tinygo-org/tinygo-site/doc-gen/internal/targetinfo" +) + +func Update(path string, ti *targetinfo.TargetInfo, updateInterfaces, updatePins bool) []error { + // Read the entire Markdown file in memory. + docBuf, err := os.ReadFile(path) + if err != nil { + return []error{fmt.Errorf("could not read Markdown file: %w", err)} + } + doc := string(docBuf) + + var interfacesUpdated, pinsUpdated bool + var errors []error + if updateInterfaces { + features := ti.SupportedFeatures() + doc, interfacesUpdated, err = updateInterfacesSection(doc, features) + if err != nil { + fmt.Fprintln(os.Stderr, "interfaces section could not be updated", err) + errors = append(errors, err) + } + } + + if updatePins { + doc, pinsUpdated, err = updatePinsSection(doc, ti) + if err != nil { + fmt.Fprintln(os.Stderr, "pins section could not be updated", err) + errors = append(errors, err) + } + } + + if !interfacesUpdated && !pinsUpdated { + return errors + } + + // Write out the updated documentation. + err = os.WriteFile(path+".tmp", []byte(doc), 0o666) + if err != nil { + errors = append(errors, fmt.Errorf("could not write updated Markdown file: %w", err)) + return errors + } + err = os.Rename(path+".tmp", path) + if err != nil { + errors = append(errors, fmt.Errorf("could not rename updated Markdown file: %w", err)) + return errors + } + + return nil +} + +func updateInterfacesSection(doc string, features map[string]bool) (string, bool, error) { + start, end, err := findSection("Interfaces", doc) + if err != nil { + // mandatory so return the error + return doc, false, err + } + + // Create new "Interfaces" section based on the previous one. + interfacesText := "## Interfaces\n\n" + + "| Interface | Hardware Supported | TinyGo Support |\n" + + "| --------- | ------------- | ----- |\n" + + for _, line := range strings.Split(doc[start:end], "\n") { + if !strings.HasPrefix(line, "| ") { + continue + } + parts := strings.Split(line, "|") + if len(parts) != 5 { + return doc, false, fmt.Errorf("expected 5 parts, got %d", len(parts)) + } + feature := strings.TrimSpace(parts[1]) + if feature == "Interface" || feature[0] == '-' { + // Part of the header. + continue + } + + // If the feature is really supported by hardware, we set the software support + // for all of known features. Unknown features keep on the manual set state. + hardwareSupport := strings.TrimSpace(parts[2]) + softwareSupport := strings.TrimSpace(parts[3]) + if hardwareSupport != "NO" && hardwareSupport != "?" { + if supported, ok := features[feature]; ok { + if supported { + softwareSupport = "YES" + } else { + softwareSupport = "Not yet" + } + } + } + interfacesText += fmt.Sprintf("| %-9s | %-3s | %-3s |\n", feature, hardwareSupport, softwareSupport) + } + + // Replace the "Interfaces" section. + return doc[:start] + interfacesText + doc[end:], true, nil +} + +func updatePinsSection(doc string, ti *targetinfo.TargetInfo) (string, bool, error) { + start, end, err := findSection("Pins", doc) + if err != nil { + // optional, so no error + fmt.Println("pins section not found - no change", err) + return doc, false, nil + } + + pinsInfo, err := ti.CreatePinsInfo() + if err != nil { + return doc, false, err + } + + pinsText := "## Pins\n\n" + + "| Pin | Hardware pin | Alternative names |" + + if pinsInfo.HasPeripheral["PWM"] { + pinsText += " PWM |" + } + pinsText += "\n| ----------------- | ------------ | ----------------- |" + for range pinsInfo.HasPeripheral { + pinsText += " -------------------- |" + } + pinsText += "\n" + for _, pin := range pinsInfo.ExposedPins { + if pin.HardwareName == "" { + return doc, false, fmt.Errorf("could not find hardware pin name for %s", pin.OtherNames[0]) + } + alternativeNames := make([]string, 0, len(pin.OtherNames)-1) + for _, name := range pin.OtherNames[1:] { + alternativeNames = append(alternativeNames, "`"+name+"`") + } + pinsText += fmt.Sprintf("| %-17s | %-12s | %-17s |", "`"+pin.OtherNames[0]+"`", "`"+pin.HardwareName+"`", + strings.Join(alternativeNames, ", ")) + for _, peripheralType := range []string{"PWM"} { + if !pinsInfo.HasPeripheral[peripheralType] { + continue + } + var peripherals []string + for _, peripheral := range pin.Peripherals[peripheralType] { + parts := strings.SplitN(peripheral, " ", 2) + s := "`" + parts[0] + "` (" + parts[1] + ")" + s = strings.ReplaceAll(s, " ", "\u00a0") // use non-breaking space + peripherals = append(peripherals, s) + } + pinsText += fmt.Sprintf(" %-20s |", strings.Join(peripherals, ", ")) + } + pinsText += "\n" + } + + // Replace the "Pins" section. + return doc[:start] + pinsText + doc[end:], true, nil +} + +func findSection(name, doc string) (start, end int, err error) { + start = strings.Index(doc, fmt.Sprintf("## %s\n", name)) + if start < 0 { + return 0, 0, fmt.Errorf("could not find '%s' header", name) + } + endOffset := strings.Index(doc[start:], "\n## ") + if endOffset < 0 { + return 0, 0, fmt.Errorf("could not find end of '%s' header", name) + } + end = start + endOffset + return +} diff --git a/doc-gen/internal/hardwarematrix/hardwarematrix.go b/doc-gen/internal/hardwarematrix/hardwarematrix.go new file mode 100644 index 00000000..2a00f4b6 --- /dev/null +++ b/doc-gen/internal/hardwarematrix/hardwarematrix.go @@ -0,0 +1,162 @@ +package hardwarematrix + +import ( + "fmt" + "os" + "path/filepath" + "regexp" + "sort" + "strings" + "text/template" +) + +var markdownTemplate = `--- +title: " Supported hardware feature matrix" +weight: 10 +description: > + Matrix between Microcontrollers and Features +--- + +Notes: +{{range $symbol, $description := .SupportedTypes}} +* '{{$symbol}}': {{$description}}{{end}} + +see TinyGo documentation of the microcontroller for details to: + +* WiFi +* BT (Bluetooth) +* IMU (Inertial measurement unit, e.g. acceleration, rotation, magnetometer) +* NePx (NeoPixel, WS2812) +* other (other peripheral or built-in devices, e.g. temperature, GSM) +{{range $_, $row := .Table}} +|{{range $_, $cell := $row}}{{$cell}}|{{end}}{{end}} +` + +var supportedTypes = map[string]string{ + supported: "Supported", + notSupported: "Not supported by Hardware", + partiallySupported: "Partially supported by TinyGo", + notYetSupported: "Not yet supported by TinyGo", + unknown: "Supported status is currently unknown", +} + +var headline = []string{ + " Microcontroller ", string(featGPIO), string(featUART), string(featSPI), + string(featI2C), string(featADC), string(featPWM), string(featUSBDev), string(featBT), string(featWiFi), + string(featIMU), string(featNP), string(featOther)} + +// PackageDoc contains all the information necessary to render the matrix documentation table. +type PackageDoc struct { + SupportedTypes map[string]string + Table [][]string +} + +var linkTitlePattern = regexp.MustCompile(`\[(.+)\]`) + +// Create creates a new document using the template. +func Create(pathToHardwareMatrix string, rowInfo []*RowInfo) error { + doc := PackageDoc{ + SupportedTypes: supportedTypes, + } + + doc.Table = append(doc.Table, headline, createSecondRow(headline)) + doc.Table = append(doc.Table, createSortedRows(headline, rowInfo, pathToHardwareMatrix)...) + + // Render the markdown of the documentation. + tpl := template.Must(template.New("markdown").Parse(markdownTemplate)) + + f, err := os.Create(pathToHardwareMatrix) + if err != nil { + return fmt.Errorf("could not open file: %w", err) + } + defer f.Close() + + return tpl.Execute(f, doc) +} + +func createSecondRow(headline []string) []string { + row := make([]string, len(headline)) + for idx, cell := range headline { + row[idx] = ":" + for i := 0; i < len(cell)-2; i++ { + row[idx] = row[idx] + "-" + } + row[idx] = row[idx] + ":" + } + + return row +} + +func createSortedRows(headline []string, rowInfos []*RowInfo, pathToHardwareMatrix string) [][]string { + var rows [][]string + firstColumn := make(map[string]struct{}) + for _, rowInfo := range rowInfos { + row := make([]string, len(headline)) + for columnIdx, hlContent := range headline { + content := notSupported + length := len(hlContent) + // strategy for the first row: + // * if link exist, use it + // * otherwise, create a link Text=title and Destination=link to md document + // * if the result is not unique for the first column, add the title after link + if columnIdx == 0 { + if rowInfo.FoundLink == nil { + if rowInfo.FoundTitle == "" { + rowInfo.FoundTitle = "?????" + } + relPath, _ := filepath.Rel(pathToHardwareMatrix, rowInfo.ControllerDocPath) + rowInfo.FoundLink = &Link{Text: rowInfo.FoundTitle, Destination: relPath} + } + if rowInfo.FoundLink != nil { + content = fmt.Sprintf("[%s](%s)", rowInfo.FoundLink.Text, rowInfo.FoundLink.Destination) + } + // try to ensure unique content + if _, ok := firstColumn[content]; ok { + content = fmt.Sprintf("%s %s", content, rowInfo.FoundTitle) + } + firstColumn[content] = struct{}{} + length = len(rowInfo.FoundLink.Destination) + length - 3 // means the visible length with collapsed link + } else { + if boardValue, ok := rowInfo.Features[feature(hlContent)]; ok { + content = boardValue + } + } + row[columnIdx] = fmt.Sprintf("%-*s", length, " "+content) + } + rows = append(rows, row) + } + + // sort by first column + sort.Slice(rows[:], func(i, j int) bool { + for x := range rows[i] { + a := strings.ToLower(rows[i][x]) + if link := linkTitlePattern.FindStringSubmatch(a); len(link) > 1 { + a = link[1] + } + b := strings.ToLower(rows[j][x]) + if link := linkTitlePattern.FindStringSubmatch(b); len(link) > 1 { + b = link[1] + } + if a == b { + continue + } + return a < b + } + return false + }) + + return rows +} + +// Update updates only what is changed, if a new controller is present, it will be added +// TODO: implement this update method - this can be done with "goldmark AST" +func Update(pathToHardwareMatrix string, rowInfo []*RowInfo) error { + /* + // TODO: goldmark.WithExtensions(extension.Table) is currently not supported by the renderer + // prepare renderer and render to md + mdRenderer := markdown.NewRenderer() + buf := bytes.Buffer{} // implements io.Writer + mdRenderer.Render(&buf, mdBufHwm, docAst) + */ + return nil +} diff --git a/doc-gen/internal/hardwarematrix/hwdescriptionrowparser.go b/doc-gen/internal/hardwarematrix/hwdescriptionrowparser.go new file mode 100644 index 00000000..7e442ee2 --- /dev/null +++ b/doc-gen/internal/hardwarematrix/hwdescriptionrowparser.go @@ -0,0 +1,387 @@ +package hardwarematrix + +import ( + "fmt" + "log" + "os" + "regexp" + "strings" + + "github.com/yuin/goldmark" + "github.com/yuin/goldmark/ast" + "github.com/yuin/goldmark/extension" + extAst "github.com/yuin/goldmark/extension/ast" + "github.com/yuin/goldmark/parser" + "github.com/yuin/goldmark/text" + "github.com/yuin/goldmark/util" +) + +const ( + supported = "x" + notSupported = "-" + partiallySupported = "p" + notYetSupported = "n" + unknown = "?" + // there are some variants, so we compare in lower case + boardDocSupported = "yes" + boardDocUnsupported = "no" + boardDocNotYet = "not yet" +) + +type feature string + +const ( + featGPIO feature = "GPIO" + featUART feature = "UART" + featSPI feature = "SPI" + featI2C feature = "I2C" + featADC feature = "ADC" + featPWM feature = "PWM" + featUSBDev feature = "USBDev" + featBT feature = "BT " + featWiFi feature = "WiFi" + featIMU feature = "IMU" + featNP feature = "NePx" + featOther feature = "other" +) + +// if those feature was found in interfaces or pins table, it will be set to "supported" +// if found in text of section "Peripherals and Drivers", it will be set to "not yet supported", if not already +// set to "supported" +var knownFeatureCatchWords = map[feature][]string{ + featGPIO: {"gpio"}, + featUART: {"uart"}, + featSPI: {"spi"}, + featI2C: {"i2c"}, + featADC: {"adc"}, + featPWM: {"pwm"}, + featUSBDev: {"usbdev", "usbdevice"}, + featBT: {"bluetooth", "bt"}, + featWiFi: {"wifi", "wi-fi"}, + featIMU: {"imu", "acceleration", "accelerometer", "gyroscope", "magnetometer", "rotation"}, + featNP: {"neopixel", "WS2812"}, +} + +var supportedFeatureCatchWords = map[feature][]string{ + featBT: {"NINA-W102", "nRF51422", "nRF51822", "nRF52832", "nrf52840"}, + featWiFi: {"NINA-W102"}, + featIMU: {"LIS3DH", "LSM6DS3", "LSM6DS33", "LSM6DS3TR", "LSM6DOX", "LSM6DSOX", "LSM9DS1", "LSM303AGR"}, +} + +// because we currently not really check "other" feature, we mark those findings as "partially supported" in general +// TODO: maybe this can be parsed from "content/docs/reference/devices/_index.md" +var otherFeatureCatchWords = map[feature][]string{ + featOther: {"APDS9960", "button", "buttons", "humidity", "HTS221", "LoRa", "LoRaWAN", "LPS22HB", "microphone", + "MicroSD", "MP34DT06JTR", "pressure", "proximity", "SD-Card", "sht3x", "temperature", "thermistor", "wan"}, +} + +type Link struct { + Text string + Destination string +} + +// key is the feature (e.g. the first cell content of a "Interfaces" table row), this will be the new table header +// the value is just the concatenation of all old cells +type features map[feature]string + +type RowInfo struct { + ControllerDocPath string // used as fallback for destination, if the link was not found + FoundTitle string // used as fallback for text, if the link was not found + FoundLink *Link + Features features +} + +type hwDescriptionToRowInfoTransformer struct { + source []byte + // -- search variables -- + searchTitlePattern *regexp.Regexp + searchPeripheralsHeading string + // interfaces table + searchInterfaceTableHeaderColumnText string + searchInterfaceTableColumnNumber int + rowInfo *RowInfo + // pins table + searchPinsTableHeaderColumnText string + // -- AST walk storage -- + mcuAllContent string + peripheralsHeadingFound bool + // table related + interfacesTableFound bool + pinsTableFound bool + columnNumberFound int + currentTableColNumber int + currentTableNextFeature string + currentTableNextFeatureAllContent string +} + +// ParseFeatureMap fill the feature map with this strategy: +// - detect the first link (to the manufacturer board description), maybe detectable by the text inside the +// [Board Name], which is the same like the "title" +// - list in section "Peripherals" found: parse list - done by catchwords +// - table in section "Interfaces" found: parse table +// - "Pins" section found: skip (TODO) +// - other section found: parse for some known tags (NINA-W102, nrf52840, ...) +func ParseFeatureMap(pathToControllerDescription string) (*RowInfo, error) { + // Read the entire Markdown file in memory. + // TODO: Parser().Parse() can also read from file + mdBuf, err := os.ReadFile(pathToControllerDescription) + if err != nil { + return nil, fmt.Errorf("could not read Markdown file: %w", err) + } + + rowInfo := RowInfo{ + ControllerDocPath: pathToControllerDescription, + Features: make(map[feature]string), + } + + // Instantiate our transformer + transformer := hwDescriptionToRowInfoTransformer{ + searchTitlePattern: regexp.MustCompile(`title: ["|'](.+)["|']`), + searchInterfaceTableHeaderColumnText: "Interface", + searchInterfaceTableColumnNumber: 1, + searchPinsTableHeaderColumnText: "Alternative names", + rowInfo: &rowInfo, + searchPeripheralsHeading: "Peripherals and Drivers", + } + // multiple AST transformers are supported, will be run in order of priority + prioritizedTransformer := util.Prioritized(&transformer, 0) + + // prepare the parser and parse to AST + gm := goldmark.New( + goldmark.WithExtensions(extension.Table), + goldmark.WithParserOptions(parser.WithASTTransformers(prioritizedTransformer)), + ) + + _ = gm.Parser().Parse(text.NewReader(mdBuf)) + //docAst.Dump(mdBuf, 2) // for debugging purposes + + return &rowInfo, nil +} + +// Transform implements goldmark.parser.ASTTransformer +func (t *hwDescriptionToRowInfoTransformer) Transform(node *ast.Document, reader text.Reader, pc parser.Context) { + // source contains the complete document, the AST objects only describes the positions in source + t.source = reader.Source() + + err := ast.Walk(node, func(node ast.Node, entering bool) (ast.WalkStatus, error) { + // Each node will be visited twice, once when it is first encountered (entering), and again + // after all the node's children have been visited (if any). + + // try to get some features from text + walkStatus, err := t.peripheralsTextToFeatures(node, entering) + if err != nil || walkStatus != ast.WalkContinue { + return walkStatus, err + } + + // try to get the MCU title to find the right link text for the first column + walkStatus, err = t.headingToMcuTitle(node, entering) + if err != nil || walkStatus != ast.WalkContinue { + return walkStatus, err + } + + // try to get the destination for the link in the first column + walkStatus, err = t.linkToLink(node, entering) + if err != nil || walkStatus != ast.WalkContinue { + return walkStatus, err + } + + walkStatus, err = t.tablesToFeatures(node, entering) + if err != nil || walkStatus != ast.WalkContinue { + return walkStatus, err + } + + return ast.WalkContinue, err + }) + + if err != nil { + log.Fatal("Error encountered while transforming AST:", err) + } +} + +func (t *hwDescriptionToRowInfoTransformer) peripheralsTextToFeatures(node ast.Node, entering bool) (ast.WalkStatus, error) { + if !entering { + return ast.WalkContinue, nil + } + + switch tnode := node.(type) { + case *ast.Heading: + content := string(tnode.Text(t.source)) + t.peripheralsHeadingFound = content == t.searchPeripheralsHeading + case *ast.Text: + content := string(tnode.Text(t.source)) + if t.peripheralsHeadingFound { + t.rowInfo.setSupportedState(content, supportedFeatureCatchWords, supported) + t.rowInfo.setSupportedState(content, knownFeatureCatchWords, notYetSupported) + t.rowInfo.setSupportedState(content, otherFeatureCatchWords, partiallySupported) + } + } + return ast.WalkContinue, nil +} + +func (t *hwDescriptionToRowInfoTransformer) headingToMcuTitle(node ast.Node, entering bool) (ast.WalkStatus, error) { + if t.rowInfo.FoundTitle != "" { + return ast.WalkContinue, nil + } + + switch tnode := node.(type) { + case *ast.Text: + if _, isHeading := tnode.Parent().(*ast.Heading); isHeading { + if entering { + //heading.Dump(t.source, 2) // for debugging purposes + newContent := string(tnode.Text(t.source)) + if strings.HasPrefix(newContent, "weight:") { + return ast.WalkContinue, nil + } + if tnode.SoftLineBreak() { + t.mcuAllContent += newContent + } else { + t.mcuAllContent = newContent + } + } else { + if tnode.SoftLineBreak() { + // content is not complete yet, continue walk + return ast.WalkContinue, nil + } + if mcu := t.searchTitlePattern.FindStringSubmatch(t.mcuAllContent); len(mcu) > 1 { + t.rowInfo.FoundTitle = mcu[1] + return ast.WalkContinue, nil + } + } + } + } + return ast.WalkContinue, nil +} + +func (t *hwDescriptionToRowInfoTransformer) linkToLink(node ast.Node, entering bool) (ast.WalkStatus, error) { + if !entering || t.rowInfo.FoundTitle == "" || t.rowInfo.FoundLink != nil { + return ast.WalkContinue, nil + } + switch tnode := node.(type) { + case *ast.Text: + if link, isLink := tnode.Parent().(*ast.Link); isLink { + //link.Dump(t.source, 2) // for debugging purposes + content := string(tnode.Text(t.source)) + // content is usually shorter than the title, because often skip the vendor/manufacturer + // nevertheless, for the hardware matrix we use the complete title rather than the shorten one + if strings.Contains(t.rowInfo.FoundTitle, content) { + t.rowInfo.FoundLink = &Link{Text: t.rowInfo.FoundTitle, Destination: string(link.Destination)} + } + } + } + return ast.WalkContinue, nil + +} + +func (t *hwDescriptionToRowInfoTransformer) tablesToFeatures(node ast.Node, entering bool) (ast.WalkStatus, error) { + switch tnode := node.(type) { + case *extAst.Table: + t.interfacesTableFound = false + t.pinsTableFound = false + t.columnNumberFound = 0 + case *extAst.TableHeader: + t.currentTableColNumber = 0 + case *extAst.TableRow: + t.currentTableColNumber = 0 + if entering { + t.currentTableNextFeature = "" + t.currentTableNextFeatureAllContent = "" + } + if !entering && t.interfacesTableFound && t.currentTableNextFeature != "" { + // on leaving the row, set the feature from found concatenated values, if not yet set to "supported" + if featState, ok := t.rowInfo.Features[feature(t.currentTableNextFeature)]; !ok || featState != supported { + t.rowInfo.Features[feature(t.currentTableNextFeature)] = convertBoardValue(t.currentTableNextFeatureAllContent) + } + } + case *extAst.TableCell: + if !entering { + return ast.WalkSkipChildren, nil + } + t.currentTableColNumber++ + cellContent := string(tnode.Text(t.source)) + if _, isHeader := tnode.Parent().(*extAst.TableHeader); isHeader { + if t.currentTableColNumber == t.searchInterfaceTableColumnNumber { + if cellContent == t.searchInterfaceTableHeaderColumnText { + t.interfacesTableFound = true + t.columnNumberFound = t.currentTableColNumber + return ast.WalkSkipChildren, nil + } + } + if cellContent == t.searchPinsTableHeaderColumnText { + t.pinsTableFound = true + t.columnNumberFound = t.currentTableColNumber + } + // all other cells of header are not important yet + return ast.WalkSkipChildren, nil + } + + // a cell/column of row after the header reached + if t.currentTableColNumber == t.columnNumberFound { + // this column contains the feature name for interfaces table + // or the list of features for pins table + + if t.interfacesTableFound { + for feat, featCatchWords := range knownFeatureCatchWords { + for _, featCatchWord := range featCatchWords { + if strings.ToLower(featCatchWord) == strings.ToLower(cellContent) { + t.currentTableNextFeature = string(feat) + return ast.WalkSkipChildren, nil + } + } + } + } + + if t.pinsTableFound { + t.rowInfo.setSupportedState(cellContent, knownFeatureCatchWords, supported) + } + + return ast.WalkSkipChildren, nil + } + + // cell/column reached after the column with possible feature + if t.interfacesTableFound && t.currentTableNextFeature != "" { + // add content of all further cells to the current + t.currentTableNextFeatureAllContent += cellContent + } + } + + return ast.WalkContinue, nil +} + +func (ri *RowInfo) setSupportedState(checkContent string, catchWords map[feature][]string, state string) { + checkContent = strings.ToLower(checkContent) + checkContent = strings.ReplaceAll(checkContent, ",", "") + checkContent = strings.ReplaceAll(checkContent, "`", "") + + splitWords := strings.Split(checkContent, " ") + for feat, featWords := range catchWords { + if featState, ok := ri.Features[feat]; ok && featState == supported { + // already set to supported + continue + } + for _, word := range splitWords { + for _, featWord := range featWords { + featWord = strings.ToLower(featWord) + if word == featWord { + ri.Features[feat] = state + continue + } + } + } + } +} + +func convertBoardValue(val string) string { + if strings.HasSuffix(strings.ToLower(val), boardDocNotYet) { + return notYetSupported + } + + if strings.HasSuffix(strings.ToLower(val), boardDocSupported) { + return supported + } + + if strings.HasPrefix(strings.ToLower(val), boardDocUnsupported) { + return notSupported + } + + return unknown +} diff --git a/doc-gen/internal/machinepackagedoc/machinepackagedoc.go b/doc-gen/internal/machinepackagedoc/machinepackagedoc.go new file mode 100644 index 00000000..7d888a99 --- /dev/null +++ b/doc-gen/internal/machinepackagedoc/machinepackagedoc.go @@ -0,0 +1,200 @@ +package machinepackagedoc + +import ( + "bytes" + "fmt" + "go/ast" + "go/printer" + "go/token" + "os" + "text/template" + + "golang.org/x/tools/go/packages" +) + +var markdownTemplateText = ` +--- +title: {{.Target}} +--- + +{{if .Constants}} +## Constants +{{range .Constants}} +{{format .}} +{{.Doc.Text}} +{{end}} +{{end}} + +{{if .Variables}} +## Variables +{{range .Variables}} +{{format .}} +{{.Doc.Text}} +{{end}} +{{end}} + +{{range $funcName, $func := .Funcs}} +### func {{$funcName}} + +{{format $func}} +{{$func.Doc.Text}} +{{end}} + +{{range $typeName, $type := .Types}} +## type {{$typeName}} + +{{format $type.Type}} +{{$type.Doc.Text}} + +{{range $funcName, $func := $type.Funcs }} +### func ({{formatReceiver $func.Recv}}) {{$funcName}} + +{{format $func}} +{{$func.Doc.Text}} +{{end}} + +{{end}} +` + +// Type an AST type plus all the functions that belong to it. +type Type struct { + Type *ast.TypeSpec + Doc *ast.CommentGroup + Funcs map[string]*ast.FuncDecl +} + +// PackageDoc contains all the information necessary to render the documentation +// of a single package. +type PackageDoc struct { + Target string + Types map[string]*Type + Funcs map[string]*ast.FuncDecl + Constants []*ast.GenDecl + Variables []*ast.GenDecl +} + +// CreateNew writes the machine package documentation new from scratch +func CreateNew(path, target string, pkg *packages.Package) error { + doc := PackageDoc{ + Target: target, + Types: make(map[string]*Type), + Funcs: make(map[string]*ast.FuncDecl), + } + + // Read everything except for functions. + for _, file := range pkg.Syntax { + for _, decl := range file.Decls { + switch decl := decl.(type) { + case *ast.GenDecl: + if decl.Tok == token.CONST || decl.Tok == token.VAR { + hasExportedNames := false + for _, spec := range decl.Specs { + for _, name := range spec.(*ast.ValueSpec).Names { + if name.IsExported() { + hasExportedNames = true + } + } + } + if hasExportedNames { + switch decl.Tok { + case token.CONST: + doc.Constants = append(doc.Constants, decl) + case token.VAR: + doc.Variables = append(doc.Variables, decl) + } + } + continue + } + for _, spec := range decl.Specs { + switch spec := spec.(type) { + case *ast.TypeSpec: + if !spec.Name.IsExported() { + continue + } + doc.Types[spec.Name.String()] = &Type{ + Type: spec, + Doc: decl.Doc, + Funcs: make(map[string]*ast.FuncDecl), + } + } + } + } + } + } + + // Read functions after types have been read, to attach functions to type + // documentation. + for _, file := range pkg.Syntax { + for _, decl := range file.Decls { + switch decl := decl.(type) { + case *ast.FuncDecl: + if !decl.Name.IsExported() { + continue + } + if decl.Recv == nil { + // TODO: check for return type + doc.Funcs[decl.Name.Name] = decl + } else { + receiver := decl.Recv.List[0].Type + var receiverName string + switch receiver := receiver.(type) { + case *ast.Ident: + receiverName = receiver.Name + case *ast.StarExpr: + receiverName = receiver.X.(*ast.Ident).Name + default: + return fmt.Errorf("unknown receiver for %s", decl.Name.Name) + } + if ast.IsExported(receiverName) { + doc.Types[receiverName].Funcs[decl.Name.Name] = decl + } + } + } + } + } + + // Render the markdown of the documentation. + tpl := template.Must(template.New("markdown").Funcs(map[string]interface{}{ + "format": func(node interface{}) string { + w := &bytes.Buffer{} + switch n := node.(type) { + case *ast.FuncDecl: + node = &ast.FuncDecl{ + Recv: n.Recv, + Name: n.Name, + Type: n.Type, + } + case *ast.TypeSpec: + node = &ast.GenDecl{ + Tok: token.TYPE, + Specs: []ast.Spec{n}, + } + case *ast.GenDecl: + node = &ast.GenDecl{ + // TODO: filter unexported specs + Tok: n.Tok, + Lparen: n.Lparen, + Specs: n.Specs, + Rparen: n.Rparen, + } + } + printer.Fprint(w, pkg.Fset, node) + text := string(w.Bytes()) + return "```go\n" + text + "\n```\n" + }, + "formatReceiver": func(receiver *ast.FieldList) string { + // Special case for formatting the receiver of a method. + w := &bytes.Buffer{} + printer.Fprint(w, pkg.Fset, receiver.List[0].Type) + return string(w.Bytes()) + }, + }).Parse(markdownTemplateText)) + + f, err := os.Create(path) + if err != nil { + return fmt.Errorf("could not open file: %w", err) + } + defer f.Close() + + return tpl.Execute(f, doc) +} diff --git a/doc-gen/internal/targetinfo/features.go b/doc-gen/internal/targetinfo/features.go new file mode 100644 index 00000000..7228338b --- /dev/null +++ b/doc-gen/internal/targetinfo/features.go @@ -0,0 +1,79 @@ +package targetinfo + +import ( + "go/ast" + "go/token" + "go/types" +) + +// SupportedFeatures check whether a given feature is supported by the chip/board based on the available types +// in the machine package and the build tags used for the compilation. +func (ti *TargetInfo) SupportedFeatures() map[string]bool { + features := map[string]bool{ + "GPIO": false, + "UART": false, + "SPI": false, + "I2C": false, + "ADC": false, + "PWM": false, + "Bluetooth": false, + "USBDevice": false, + } + + pkg := ti.Pkg + + pinType := pkg.Types.Scope().Lookup("Pin").Type() + if types.NewMethodSet(pinType).Lookup(pkg.Types, "Get") != nil { + // Note: checking the 'Get' method because the 'Set' method is always + // implemented (even if it's a no-op). + features["GPIO"] = true + } + if pkg.Types.Scope().Lookup("UART") != nil { + features["UART"] = true + } + if pkg.Types.Scope().Lookup("SPI") != nil { + features["SPI"] = true + } + if pkg.Types.Scope().Lookup("I2C") != nil { + features["I2C"] = true + } + adcType := pkg.Types.Scope().Lookup("ADC").Type() + if types.NewMethodSet(adcType).Lookup(pkg.Types, "Configure") != nil { + features["ADC"] = true + } + for _, tag := range ti.BuildTags { + if tag == "nrf51" || tag == "nrf52" || tag == "nrf52840" || tag == "nrf52833" { + features["Bluetooth"] = true + } + } + if pkg.Types.Scope().Lookup("USBDevice") != nil { + features["USBDevice"] = true + } + + // Detecting PWM support is a bit more tricky. + // We basically iterate over all global variables and check whether they + // have Configure method that takes a single PWMConfig struct. + for _, file := range pkg.Syntax { + for _, decl := range file.Decls { + switch decl := decl.(type) { + case *ast.GenDecl: + if decl.Tok != token.VAR { + continue + } + for _, spec := range decl.Specs { + // Found a global variable. + spec := spec.(*ast.ValueSpec) + name := spec.Names[0].Name + if !ast.IsExported(name) { + continue + } + if classifyPeripheral(pkg, name) == "PWM" { + features["PWM"] = true + } + } + } + } + } + + return features +} diff --git a/doc-gen/internal/targetinfo/pininfo.go b/doc-gen/internal/targetinfo/pininfo.go new file mode 100644 index 00000000..e74a4d26 --- /dev/null +++ b/doc-gen/internal/targetinfo/pininfo.go @@ -0,0 +1,165 @@ +package targetinfo + +import ( + "fmt" + "go/ast" + "go/constant" + "go/token" + "go/types" + "regexp" + "strings" +) + +// AnyPin holds information about an arbitrary pin +type AnyPin struct { + HardwareName string + OtherNames []string + Peripherals map[string][]string +} + +// PinsInfo holds information about all pins which are suitable for the documentation +type PinsInfo struct { + HasPeripheral map[string]bool + ExposedPins []*AnyPin +} + +// Match formats: +// - PA0 (AVR) +// - PA00 (Microchip SAM series) +// - P0_00 (nrf series), +// - GPIO0 (esp series, rp2040) +// - P00 (sifive) +var pinIsHardwareName = regexp.MustCompile("^(P[A-Z][0-9]+|P[0-1]_[0-9]{2}|GPIO[0-9]+|P[0-9]{2})$") + +// CreatePinsInfo creates info about all pins contained in the target info package +func (ti *TargetInfo) CreatePinsInfo() (*PinsInfo, error) { + // There is a pins section. Update it from the machine package. + supportedPeripherals := map[string]bool{ + "PWM": true, + } + + pkg := ti.Pkg + + // Find board pin names + pinNames := make(map[string]uint64) + hardwarePins := make(map[string]struct{}) + pinPeripherals := make(map[string][]string) + var pinNamesSlice []string + for _, file := range pkg.Syntax { + for _, decl := range file.Decls { + switch decl := decl.(type) { + case *ast.GenDecl: + if decl.Tok != token.CONST { + continue + } + for _, spec := range decl.Specs { + // Found a constant. + spec := spec.(*ast.ValueSpec) + name := spec.Names[0].Name + if !ast.IsExported(name) { + continue + } + obj := pkg.Types.Scope().Lookup(name) + if obj.Type().String() != "machine.Pin" { + continue + } + val, ok := constant.Uint64Val(obj.(*types.Const).Val()) + if !ok { + return nil, fmt.Errorf("expected pin %s with value %s to be representable by uint64", + name, obj.(*types.Const).Val()) + } + pinNamesSlice = append(pinNamesSlice, name) + pinNames[name] = val + if isHardwarePin(name, spec.Values) { + hardwarePins[name] = struct{}{} + comment := strings.TrimSpace(spec.Comment.Text()) + if strings.HasPrefix(comment, "peripherals: ") { + pinPeripherals[name] = strings.Split(strings.TrimPrefix(comment, "peripherals: "), ", ") + } + } + } + } + } + } + if _, ok := pinNames["NoPin"]; !ok { + return nil, fmt.Errorf("could not find NoPin constant") + } + + pins := make(map[uint64]*AnyPin) + pi := PinsInfo{ + HasPeripheral: make(map[string]bool), + } + + for _, name := range pinNamesSlice { + if name == "NoPin" || pinNames[name] == pinNames["NoPin"] { + continue + } + num := pinNames[name] + pin, ok := pins[num] + if !ok { + pin = &AnyPin{Peripherals: map[string][]string{}} + pins[num] = pin + } + if _, ok := hardwarePins[name]; ok { + // Hardware name + if pin.HardwareName != "" { + return nil, fmt.Errorf("duplicate hardware pin name: %s and %s", pin.HardwareName, name) + } + pin.HardwareName = name + for _, peripheral := range pinPeripherals[name] { + peripheralName := strings.SplitN(peripheral, " ", 2)[0] + peripheralType := classifyPeripheral(pkg, peripheralName) + if supportedPeripherals[peripheralType] { + pin.Peripherals[peripheralType] = append(pin.Peripherals[peripheralType], peripheral) + pi.HasPeripheral[peripheralType] = true + } + } + } else { + // Other name + if len(pin.OtherNames) == 0 { + pi.ExposedPins = append(pi.ExposedPins, pin) + } + pin.OtherNames = append(pin.OtherNames, name) + } + } + + return &pi, nil +} + +// isHardwarePin return whether this pin looks like a hardware pin name. A hardware pin constant is a constant like PB02 +// on the Arduino: a constant defined by the chip, and not the board (which would be pin 13, D13, or the LED pin). +func isHardwarePin(name string, values []ast.Expr) bool { + if !pinIsHardwareName.MatchString(name) { + return false + } + if len(values) == 0 { + // Pin constant is probably part of a constant like this: + // const ( + // GPIO0 Pin = iota + // GPIO1 + // GPIO2 + // // etc + // ) + return true + } + switch value := values[0].(type) { + case *ast.BasicLit: + // For example: + // const GPIO5 Pin = 5 + return true + case *ast.BinaryExpr: + // For example: + // const PB02 = portB + 2 + return true + case *ast.Ident: + if value.Name == "iota" { + // Pins are initialized using the special identifier "iota". + return true + } + // Doesn't look like a hardware pin, could be something like: + // const D13 = PB5 + return false + default: + return false + } +} diff --git a/doc-gen/internal/targetinfo/targetinfo.go b/doc-gen/internal/targetinfo/targetinfo.go new file mode 100644 index 00000000..58db4312 --- /dev/null +++ b/doc-gen/internal/targetinfo/targetinfo.go @@ -0,0 +1,104 @@ +package targetinfo + +import ( + "fmt" + "go/types" + "log" + "os" + "os/exec" + "strings" + + "golang.org/x/tools/go/packages" +) + +// TargetInfo contains info attributes of the target +type TargetInfo struct { + BuildTags []string + Pkg *packages.Package +} + +// Create retrieves some information about the given target +func Create(target string) (*TargetInfo, error) { + // Get the important information from the compiler. + cmd := exec.Command("tinygo", "info", target) + outBytes, err := cmd.Output() + if err != nil { + return nil, fmt.Errorf("could not run tinygo: %v", err) + } + + var buildTags []string + var goos, goarch, goroot string + for _, line := range strings.Split(string(outBytes), "\n") { + idx := strings.IndexByte(line, ':') + if idx < 0 { + continue + } + key := strings.TrimSpace(line[:idx]) + value := strings.TrimSpace(line[idx+1:]) + switch key { + case "build tags": + buildTags = strings.Fields(value) + case "GOOS": + goos = value + case "GOARCH": + goarch = value + case "cached GOROOT": + goroot = value + } + } + if len(buildTags) == 0 || goos == "" || goarch == "" || goroot == "" { + return nil, fmt.Errorf("could not find all needed properties (build tags, GOOS, GOARCH, GOROOT)") + } + + // Get the list of files that would be compiled for this package. + pkgs, err := packages.Load(&packages.Config{ + Mode: packages.NeedName | packages.NeedSyntax | packages.NeedTypes | packages.NeedDeps, + BuildFlags: []string{"-tags=" + strings.Join(buildTags, " ")}, + Env: append(os.Environ(), "GOOS="+goos, "GOARCH="+goarch, "GOROOT="+goroot, "GO111MODULE=off"), + }, "machine") + if err != nil { + log.Fatal(err) + } + + // Do some sanity checking. + if len(pkgs[0].Errors) != 0 { + fmt.Fprintf(os.Stderr, " sanity check failed with %d error(s)\n", len(pkgs[0].Errors)) + for _, err := range pkgs[0].Errors { + fmt.Fprintf(os.Stderr, " * %v\n", err) + } + return nil, fmt.Errorf("sanity check failed") + } + + ti := TargetInfo{ + Pkg: pkgs[0], + BuildTags: buildTags, + } + + return &ti, nil +} + +// classifyPeripheral returns the peripheral type for a given peripheral name, by looking at the type of the global. +func classifyPeripheral(pkg *packages.Package, name string) string { + global := pkg.Types.Scope().Lookup(name) + if global == nil { + // The peripheral is not available. + // This sometimes happen when the pins are defined for a chip family but + // some chips don't have all the peripherals. + return "" + } + + // Check for Configure method. Most peripherals have one. + configureMethod := types.NewMethodSet(global.Type()).Lookup(pkg.Types, "Configure") + if configureMethod == nil { + return "" + } + + // Check whether it has just one parameter and this parameter is of type + // PWMConfig. + params := configureMethod.Type().(*types.Signature).Params() + if params.Len() == 1 && params.At(0).Type() == pkg.Types.Scope().Lookup("PWMConfig").Type() { + return "PWM" + } + // Some other kind of peripheral. + return "" +} diff --git a/doc-gen/main.go b/doc-gen/main.go deleted file mode 100644 index 818a48d1..00000000 --- a/doc-gen/main.go +++ /dev/null @@ -1,644 +0,0 @@ -package main - -import ( - "bytes" - "fmt" - "go/ast" - "go/constant" - "go/printer" - "go/token" - "go/types" - "io/ioutil" - "log" - "os" - "os/exec" - "path/filepath" - "regexp" - "strings" - "text/template" - - "golang.org/x/tools/go/packages" -) - -// PackageDoc contains all the information necessary to render the documentation -// of a single package. -type PackageDoc struct { - Target string - Types map[string]*Type - Funcs map[string]*ast.FuncDecl - Constants []*ast.GenDecl - Variables []*ast.GenDecl -} - -// Type an AST type plus all the functions that belong to it. -type Type struct { - Type *ast.TypeSpec - Doc *ast.CommentGroup - Funcs map[string]*ast.FuncDecl -} - -type Pin struct { - HardwareName string - OtherNames []string - Peripherals map[string][]string -} - -// Match formats: -// - PA0 (AVR) -// - PA00 (Microchip SAM series) -// - P0_00 (nrf series), -// - GPIO0 (esp series, rp2040) -// - P00 (sifive) -var pinIsHardwareName = regexp.MustCompile("^(P[A-Z][0-9]+|P[0-1]_[0-9]{2}|GPIO[0-9]+|P[0-9]{2})$") - -var markdownTemplateText = ` ---- -title: {{.Target}} ---- - -{{if .Constants}} -## Constants -{{range .Constants}} -{{format .}} -{{.Doc.Text}} -{{end}} -{{end}} - -{{if .Variables}} -## Variables -{{range .Variables}} -{{format .}} -{{.Doc.Text}} -{{end}} -{{end}} - -{{range $funcName, $func := .Funcs}} -### func {{$funcName}} - -{{format $func}} -{{$func.Doc.Text}} -{{end}} - -{{range $typeName, $type := .Types}} -## type {{$typeName}} - -{{format $type.Type}} -{{$type.Doc.Text}} - -{{range $funcName, $func := $type.Funcs }} -### func ({{formatReceiver $func.Recv}}) {{$funcName}} - -{{format $func}} -{{$func.Doc.Text}} -{{end}} - -{{end}} -` - -func main() { - // Get the target from the list of command line options. - for _, target := range os.Args[1:] { - path := filepath.Join("..", "content", "docs", "reference", "microcontrollers", "machine", target+".md") - docPath := filepath.Join("..", "content", "docs", "reference", "microcontrollers", target+".md") - if _, err := os.Stat(docPath); err != nil { - fmt.Println("Skipping: ", target) - continue - } - fmt.Println("Generating documentation for:", target) - updateDocumentation(target, path, docPath) - } -} - -func updateDocumentation(target, path, docPath string) { - // Get the important information from the compiler. - cmd := exec.Command("tinygo", "info", target) - outBytes, err := cmd.Output() - if err != nil { - fmt.Fprintln(os.Stderr, "could not run tinygo:", err) - os.Exit(1) - } - var buildTags []string - var goos, goarch, goroot string - for _, line := range strings.Split(string(outBytes), "\n") { - idx := strings.IndexByte(line, ':') - if idx < 0 { - continue - } - key := strings.TrimSpace(line[:idx]) - value := strings.TrimSpace(line[idx+1:]) - switch key { - case "build tags": - buildTags = strings.Fields(value) - case "GOOS": - goos = value - case "GOARCH": - goarch = value - case "cached GOROOT": - goroot = value - } - } - if len(buildTags) == 0 || goos == "" || goarch == "" || goroot == "" { - fmt.Fprintln(os.Stderr, "could not find all needed properties (build tags, GOOS, GOARCH, GOROOT)") - os.Exit(1) - } - - // Get the list of files that would be compiled for this package. - pkgs, err := packages.Load(&packages.Config{ - Mode: packages.NeedName | packages.NeedSyntax | packages.NeedTypes | packages.NeedDeps, - BuildFlags: []string{"-tags=" + strings.Join(buildTags, " ")}, - Env: append(os.Environ(), "GOOS="+goos, "GOARCH="+goarch, "GOROOT="+goroot, "GO111MODULE=off"), - }, "machine") - if err != nil { - log.Fatal(err) - } - - // Do some sanity checking. - if len(pkgs[0].Errors) != 0 { - for _, err := range pkgs[0].Errors { - fmt.Fprintln(os.Stderr, err) - } - os.Exit(1) - } - pkg := pkgs[0] - - err = writeMachinePackageDoc(path, target, pkg) - if err != nil { - fmt.Fprintln(os.Stderr, "error:", err) - os.Exit(1) - } - - err = updateBoardDocumentation(docPath, pkg, buildTags) - if err != nil { - fmt.Fprintln(os.Stderr, "error:", err) - os.Exit(1) - } -} - -func writeMachinePackageDoc(path, target string, pkg *packages.Package) error { - doc := PackageDoc{ - Target: target, - Types: make(map[string]*Type), - Funcs: make(map[string]*ast.FuncDecl), - } - - // Read everything except for functions. - for _, file := range pkg.Syntax { - for _, decl := range file.Decls { - switch decl := decl.(type) { - case *ast.GenDecl: - if decl.Tok == token.CONST || decl.Tok == token.VAR { - hasExportedNames := false - for _, spec := range decl.Specs { - for _, name := range spec.(*ast.ValueSpec).Names { - if name.IsExported() { - hasExportedNames = true - } - } - } - if hasExportedNames { - switch decl.Tok { - case token.CONST: - doc.Constants = append(doc.Constants, decl) - case token.VAR: - doc.Variables = append(doc.Variables, decl) - } - } - continue - } - for _, spec := range decl.Specs { - switch spec := spec.(type) { - case *ast.TypeSpec: - if !spec.Name.IsExported() { - continue - } - doc.Types[spec.Name.String()] = &Type{ - Type: spec, - Doc: decl.Doc, - Funcs: make(map[string]*ast.FuncDecl), - } - } - } - } - } - } - - // Read functions after types have been read, to attach functions to type - // documentation. - for _, file := range pkg.Syntax { - for _, decl := range file.Decls { - switch decl := decl.(type) { - case *ast.FuncDecl: - if !decl.Name.IsExported() { - continue - } - if decl.Recv == nil { - // TODO: check for return type - doc.Funcs[decl.Name.Name] = decl - } else { - receiver := decl.Recv.List[0].Type - var receiverName string - switch receiver := receiver.(type) { - case *ast.Ident: - receiverName = receiver.Name - case *ast.StarExpr: - receiverName = receiver.X.(*ast.Ident).Name - default: - return fmt.Errorf("unknown receiver for %s", decl.Name.Name) - } - if ast.IsExported(receiverName) { - doc.Types[receiverName].Funcs[decl.Name.Name] = decl - } - } - } - } - } - - // Render the markdown of the documentation. - tpl := template.Must(template.New("markdown").Funcs(map[string]interface{}{ - "format": func(node interface{}) string { - w := &bytes.Buffer{} - switch n := node.(type) { - case *ast.FuncDecl: - node = &ast.FuncDecl{ - Recv: n.Recv, - Name: n.Name, - Type: n.Type, - } - case *ast.TypeSpec: - node = &ast.GenDecl{ - Tok: token.TYPE, - Specs: []ast.Spec{n}, - } - case *ast.GenDecl: - node = &ast.GenDecl{ - // TODO: filter unexported specs - Tok: n.Tok, - Lparen: n.Lparen, - Specs: n.Specs, - Rparen: n.Rparen, - } - } - printer.Fprint(w, pkg.Fset, node) - text := string(w.Bytes()) - return "```go\n" + text + "\n```\n" - }, - "formatReceiver": func(receiver *ast.FieldList) string { - // Special case for formatting the receiver of a method. - w := &bytes.Buffer{} - printer.Fprint(w, pkg.Fset, receiver.List[0].Type) - return string(w.Bytes()) - }, - }).Parse(markdownTemplateText)) - - f, err := os.Create(path) - if err != nil { - return fmt.Errorf("could not open file: %w", err) - } - defer f.Close() - - return tpl.Execute(f, doc) -} - -func findSection(name, doc string) (start, end int, err error) { - start = strings.Index(doc, fmt.Sprintf("## %s\n", name)) - if start < 0 { - return 0, 0, fmt.Errorf("could not find '%s' header", name) - } - endOffset := strings.Index(doc[start:], "\n## ") - if endOffset < 0 { - return 0, 0, fmt.Errorf("could not find end of '%s' header", name) - } - end = start + endOffset - return -} - -func updateBoardDocumentation(path string, pkg *packages.Package, buildTags []string) error { - features := detectSupportedFeatures(pkg, buildTags) - - // Read the entire Markdown file in memory. - docBuf, err := ioutil.ReadFile(path) - if err != nil { - return fmt.Errorf("could not read Markdown file: %w", err) - } - doc := string(docBuf) - - // Find "Interfaces" section. - start, end, err := findSection("Interfaces", doc) - if err != nil { - return err - } - - // Create new "Interfaces" section based on the previous section. - interfacesText := "## Interfaces\n\n| Interface | Hardware Supported | TinyGo Support |\n| --------- | ------------- | ----- |\n" - for _, line := range strings.Split(doc[start:end], "\n") { - if !strings.HasPrefix(line, "| ") { - continue - } - parts := strings.Split(line, "|") - if len(parts) != 5 { - return fmt.Errorf("expected 5 parts, got %d", len(parts)) - } - feature := strings.TrimSpace(parts[1]) - if feature == "Interface" || feature[0] == '-' { - // Part of the hearder. - continue - } - hardwareSupport := strings.TrimSpace(parts[2]) - softwareSupport := strings.TrimSpace(parts[3]) - if hardwareSupport != "NO" && hardwareSupport != "?" { - if supported, ok := features[feature]; ok { - if supported { - softwareSupport = "YES" - } else { - softwareSupport = "Not yet" - } - } - } - interfacesText += fmt.Sprintf("| %-9s | %-3s | %-3s |\n", feature, hardwareSupport, softwareSupport) - } - - // Replace the "Interfaces" section. - doc = doc[:start] + interfacesText + doc[end:] - - start, end, err = findSection("Pins", doc) - if err == nil { - // There is a pins section. Update it from the machine package. - pinsText, err := getPinsSection(pkg) - if err != nil { - return err - } - - // Replace the "Pins" section. - doc = doc[:start] + pinsText + doc[end:] - } - - // Write out the updated documentation. - err = ioutil.WriteFile(path+".tmp", []byte(doc), 0o666) - if err != nil { - return fmt.Errorf("could not write updated Markdown file: %w", err) - } - err = os.Rename(path+".tmp", path) - if err != nil { - return fmt.Errorf("could not rename updated Markdown file: %w", err) - } - - return nil -} - -// detectSupportedFeatures check whether a given feature is supported by the -// chip/board based on the available types in the machine package and the build -// tags used for the compilation. -func detectSupportedFeatures(pkg *packages.Package, buildTags []string) map[string]bool { - features := map[string]bool{ - "GPIO": false, - "UART": false, - "SPI": false, - "I2C": false, - "ADC": false, - "PWM": false, - "Bluetooth": false, - "USBDevice": false, - } - - pinType := pkg.Types.Scope().Lookup("Pin").Type() - if types.NewMethodSet(pinType).Lookup(pkg.Types, "Get") != nil { - // Note: checking the 'Get' method because the 'Set' method is always - // implemented (even if it's a no-op). - features["GPIO"] = true - } - if pkg.Types.Scope().Lookup("UART") != nil { - features["UART"] = true - } - if pkg.Types.Scope().Lookup("SPI") != nil { - features["SPI"] = true - } - if pkg.Types.Scope().Lookup("I2C") != nil { - features["I2C"] = true - } - adcType := pkg.Types.Scope().Lookup("ADC").Type() - if types.NewMethodSet(adcType).Lookup(pkg.Types, "Configure") != nil { - features["ADC"] = true - } - for _, tag := range buildTags { - if tag == "nrf51" || tag == "nrf52" || tag == "nrf52840" || tag == "nrf52833" { - features["Bluetooth"] = true - } - } - if pkg.Types.Scope().Lookup("USBDevice") != nil { - features["USBDevice"] = true - } - - // Detecting PWM support is a bit more tricky. - // We basically iterate over all global variables and check whether they - // have Configure method that takes a single PWMConfig struct. - for _, file := range pkg.Syntax { - for _, decl := range file.Decls { - switch decl := decl.(type) { - case *ast.GenDecl: - if decl.Tok != token.VAR { - continue - } - for _, spec := range decl.Specs { - // Found a global variable. - spec := spec.(*ast.ValueSpec) - name := spec.Names[0].Name - if !ast.IsExported(name) { - continue - } - if classifyPeripheral(pkg, name) == "PWM" { - features["PWM"] = true - } - } - } - } - } - - return features -} - -func getPinsSection(pkg *packages.Package) (string, error) { - supportedPeripherals := map[string]bool{ - "PWM": true, - } - - // Find board pin names - pinNames := make(map[string]uint64) - hardwarePins := make(map[string]struct{}) - pinPeripherals := make(map[string][]string) - var pinNamesSlice []string - for _, file := range pkg.Syntax { - for _, decl := range file.Decls { - switch decl := decl.(type) { - case *ast.GenDecl: - if decl.Tok != token.CONST { - continue - } - for _, spec := range decl.Specs { - // Found a constant. - spec := spec.(*ast.ValueSpec) - name := spec.Names[0].Name - if !ast.IsExported(name) { - continue - } - obj := pkg.Types.Scope().Lookup(name) - if obj.Type().String() != "machine.Pin" { - continue - } - val, ok := constant.Uint64Val(obj.(*types.Const).Val()) - if !ok { - return "", fmt.Errorf("expected pin %s with value %s to be representable by uint64", name, obj.(*types.Const).Val()) - } - pinNamesSlice = append(pinNamesSlice, name) - pinNames[name] = val - if isHardwarePin(name, spec.Values) { - hardwarePins[name] = struct{}{} - comment := strings.TrimSpace(spec.Comment.Text()) - if strings.HasPrefix(comment, "peripherals: ") { - pinPeripherals[name] = strings.Split(strings.TrimPrefix(comment, "peripherals: "), ", ") - } - } - } - } - } - } - if _, ok := pinNames["NoPin"]; !ok { - return "", fmt.Errorf("could not find NoPin constant") - } - var exposedPins []*Pin - pins := make(map[uint64]*Pin) - hasPeripheral := make(map[string]bool) - for _, name := range pinNamesSlice { - if name == "NoPin" || pinNames[name] == pinNames["NoPin"] { - continue - } - num := pinNames[name] - pin, ok := pins[num] - if !ok { - pin = &Pin{Peripherals: map[string][]string{}} - pins[num] = pin - } - if _, ok := hardwarePins[name]; ok { - // Hardware name - if pin.HardwareName != "" { - return "", fmt.Errorf("duplicate hardware pin name: %s and %s", pin.HardwareName, name) - } - pin.HardwareName = name - for _, peripheral := range pinPeripherals[name] { - peripheralName := strings.SplitN(peripheral, " ", 2)[0] - peripheralType := classifyPeripheral(pkg, peripheralName) - if supportedPeripherals[peripheralType] { - pin.Peripherals[peripheralType] = append(pin.Peripherals[peripheralType], peripheral) - hasPeripheral[peripheralType] = true - } - } - } else { - // Other name - if len(pin.OtherNames) == 0 { - exposedPins = append(exposedPins, pin) - } - pin.OtherNames = append(pin.OtherNames, name) - } - } - - pinsText := "## Pins\n\n| Pin | Hardware pin | Alternative names |" - if hasPeripheral["PWM"] { - pinsText += " PWM |" - } - pinsText += "\n| ----------------- | ------------ | ----------------- |" - for range hasPeripheral { - pinsText += " -------------------- |" - } - pinsText += "\n" - for _, pin := range exposedPins { - if pin.HardwareName == "" { - return "", fmt.Errorf("could not find hardware pin name for %s", pin.OtherNames[0]) - } - alternativeNames := make([]string, 0, len(pin.OtherNames)-1) - for _, name := range pin.OtherNames[1:] { - alternativeNames = append(alternativeNames, "`"+name+"`") - } - pinsText += fmt.Sprintf("| %-17s | %-12s | %-17s |", "`"+pin.OtherNames[0]+"`", "`"+pin.HardwareName+"`", strings.Join(alternativeNames, ", ")) - for _, peripheralType := range []string{"PWM"} { - if !hasPeripheral[peripheralType] { - continue - } - var peripherals []string - for _, peripheral := range pin.Peripherals[peripheralType] { - parts := strings.SplitN(peripheral, " ", 2) - s := "`" + parts[0] + "` (" + parts[1] + ")" - s = strings.ReplaceAll(s, " ", "\u00a0") // use non-breaking space - peripherals = append(peripherals, s) - } - pinsText += fmt.Sprintf(" %-20s |", strings.Join(peripherals, ", ")) - } - pinsText += "\n" - } - - return pinsText, nil -} - -// Return whether this pin looks like a hardware pin name. A hardware pin -// constant is a constant like PB02 on the Arduino: a constant defined by the -// chip, and not the board (which would be pin 13, D13, or the LED pin). -func isHardwarePin(name string, values []ast.Expr) bool { - if !pinIsHardwareName.MatchString(name) { - return false - } - if len(values) == 0 { - // Pin constant is probably part of a constant like this: - // const ( - // GPIO0 Pin = iota - // GPIO1 - // GPIO2 - // // etc - // ) - return true - } - switch value := values[0].(type) { - case *ast.BasicLit: - // For example: - // const GPIO5 Pin = 5 - return true - case *ast.BinaryExpr: - // For example: - // const PB02 = portB + 2 - return true - case *ast.Ident: - if value.Name == "iota" { - // Pins are initialized using the special identifier "iota". - return true - } - // Doesn't look like a hardware pin, could be something like: - // const D13 = PB5 - return false - default: - return false - } -} - -// Return the peripheral type for a given peripheral name, by looking at the -// type of the global. -func classifyPeripheral(pkg *packages.Package, name string) string { - global := pkg.Types.Scope().Lookup(name) - if global == nil { - // The peripheral is not available. - // This sometimes happen when the pins are defined for a chip family but - // some chips don't have all the peripherals. - return "" - } - - // Check for Configure method. Most peripherals have one. - configureMethod := types.NewMethodSet(global.Type()).Lookup(pkg.Types, "Configure") - if configureMethod == nil { - return "" - } - - // Check whether it has just one parameter and this parameter is of type - // PWMConfig. - params := configureMethod.Type().(*types.Signature).Params() - if params.Len() == 1 && params.At(0).Type() == pkg.Types.Scope().Lookup("PWMConfig").Type() { - return "PWM" - } - // Some other kind of peripheral. - return "" -} diff --git a/imports/main.go b/imports/main.go index 7097b552..8608e3da 100644 --- a/imports/main.go +++ b/imports/main.go @@ -3,7 +3,6 @@ package main import ( "bytes" "fmt" - "io/ioutil" "os" "os/exec" "path/filepath" @@ -241,13 +240,13 @@ func (pkg *Package) runTest() (result testResult) { result.pkg = pkg // Prepare test files. - dir, err := ioutil.TempDir("", "tinygo-test-*") + dir, err := os.MkdirTemp("", "tinygo-test-*") if err != nil { panic("could not create temporary directory: " + err.Error()) } defer os.RemoveAll(dir) temporaryGoFile := filepath.Join(dir, "main.go") - ioutil.WriteFile(temporaryGoFile, []byte(fmt.Sprintf("package main\nimport _ \"%s\"\nfunc main(){}\n", pkg.Path)), 0600) + os.WriteFile(temporaryGoFile, []byte(fmt.Sprintf("package main\nimport _ \"%s\"\nfunc main(){}\n", pkg.Path)), 0600) temporaryExecutableFile := filepath.Join(dir, "main") // Run the compile test.