wifinina

package
v0.0.0-...-7691dab Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2022 License: BSD-3-Clause Imports: 11 Imported by: 0

README

WifiNINA Driver

This package provides a driver to use a separate connected WiFi processor ESP32 for TCP/UDP communication.

The way this driver works is by using the SPI interface of your microcontroller to communicate with the WiFi chip using the Arduino SPI command set.

Using the WiFiNINA Driver

For information on how to use this driver, please take a look at the examples located in the examples/wifinina directory.

Firmware

PLEASE NOTE: New Adafruit Boards with WiFi and Arduino Nano33 IoT and Nano RP2040 Connect boards most likely already have a recent version of the nina-fw firmware pre-installed. You should not need to install the firmware yourself.

In order to use this driver, you must have the nina-fw firmware installed on the ESP32 chip. If it is already installed, you can just use it. You do not need to flash the firmware again unless it has known bugs or lacks functionality you plan to use.

The following instructions are only for those who want or need to update the firmware on your board.

Update Arduino Boards with Arduino IDE

Probably, the easiest way to update nina-fw on Arduino boards is to use their IDE. Please see tutorial page for detailed instructions.

Sometimes you may want to flash a version of nina-fw Arduino IDE does not know about yet.
There is no way to "refresh" firmware versions list, but you can "fool" Arduino IDE by substituting, say, 1.4.5 binary with 1.4.8 binary.
For that you need to locate the binary Arduino IDE going to flash and replace it with a new file.
Location differs from OS to OS, on macOS it's in "/Applications/Arduino.app/Contents/Java/tools/WiFi101/tool/firmwares/NINA/".
Replace respective binary ".bin" file with new file and follow tutorial steps above flashing "1.4.5" version while in fact it is going to flash "1.4.8".

Latest firmware binary file for your board can be downloaded from their releases page.

Verify correct version flashed with "Examples/WiFiNINA/Tools/CheckFirmwareVersion" sketch in Arduino IDE.

Update Arduino Boards without Arduino IDE
Download nina-fw firmware binary
# wget
wget https://github.com/arduino/nina-fw/releases/download/1.4.8/NINA_W102-v1.4.8.bin
# curl
curl -LO https://github.com/arduino/nina-fw/releases/download/1.4.8/NINA_W102-v1.4.8.bin
Install esptool to flash nina-fw firmware

In order to flash the firmware, you need to use Python to install the esptool package.

pip install esptool

On macOS you can also use brew

brew install esptool

Once you have installed esptool you can follow the procedure below for flashing your board.

Note: We use esptool executable in the rest of the document, you may find yourself using esptool.py instead, depends on OS and way you install it. Note: Port /dev/ttyACM0 is valid for Linux; on macOS it shall be something like /dev/tty.usbmodem14101; on Windows expect to see COM1 or alike.

Update nina-fw on the Arduino Nano33 IoT

In the updater directory we have a precompiled binary of the "passthrough" code you will need to flash first, in order to update the ESP32 co-processor on your board.

This is what needs to be done. There is also a bash script that performs the same steps also located in the updater directory.


# reset board into bootloader mode using 1200 baud
stty -F /dev/ttyACM0 ispeed 1200 ospeed 1200

# flash the passthru binary to the SAMD21 using bossac
# code from https://github.com/arduino-libraries/WiFiNINA/blob/master/examples/Tools/SerialNINAPassthrough/SerialNINAPassthrough.ino
bossac -d -i -e -w -v -R --port=/dev/ttyACM0 --offset=0x2000 ./SerialNINAPassthrough.ino.nano_33_iot.bin

# flash the nina-fw binary to the ESP32 using esptool
esptool --port /dev/ttyACM0 --before default_reset --baud 115200 write_flash 0 ./NINA_W102-v1.4.8.bin

You only need to do this one time, and then the correct nina-fw firmware will be on the NINA ESP32 chip, and you can just flash the Arduino Nano33 IoT board using TinyGo.

Update nina-fw on the Arduino Nano RP2040 Connect

In the updater directory we have a precompiled binary of the "passthrough" code you will need to flash first, in order to update the ESP32 co-processor on your board.

Put Nano RP2040 Connect into Mass Storage Device mode by shorting REC and GND pins while plugging it in. Alternatively you can short the pins and press button on top side of the board while keeping the board connected to your computer. Release the pins and "RPI-RP2" storage device shall appear mounted.

Copy SerialNINAPassthrough.ino.nano_rp2040_connect.uf2 file over to storage device and it must eject rebooting.

Now you can use esptool to flash nina-fw to ESP32 chip on the board.

esptool --port /dev/ttyACM0 --before no_reset --baud 115200 write_flash 0 ./NINA_W102-v1.4.8.bin

Verify correct version of nina-fw installed by flasing CheckFirmwareVersion.ino.uf2 on the board the same way you flashed SerialNINAPassthrough.ino.nano_rp2040_connect.uf2 before. You must connect to the board with a serial monitor, for example Arduino IDE, alternatively screen or picocom cli commands.

Update Adafruit ESP32 WiFi Boards

Adafruit provides very good instructions for updating their boards that provide a ESP32 WiFi-BLE co-processor. For more information, please see:

https://learn.adafruit.com/upgrading-esp32-firmware

Documentation

Overview

Package wifinina implements TCP wireless communication over SPI with an attached separate ESP32 board using the Arduino WiFiNINA protocol.

In order to use this driver, the ESP32 must be flashed with specific firmware from Arduino. For more information: https://github.com/arduino/nina-fw

Index

Constants

View Source
const (
	PinLow uint8 = iota
	PinHigh
)
View Source
const (
	MaxSockets  = 4
	MaxNetworks = 10
	MaxAttempts = 10

	MaxLengthSSID   = 32
	MaxLengthWPAKey = 63
	MaxLengthWEPKey = 13

	LengthMacAddress = 6
	LengthIPV4       = 4

	WlFailure = -1
	WlSuccess = 1

	StatusNoShield       ConnectionStatus = 255
	StatusIdle           ConnectionStatus = 0
	StatusNoSSIDAvail    ConnectionStatus = 1
	StatusScanCompleted  ConnectionStatus = 2
	StatusConnected      ConnectionStatus = 3
	StatusConnectFailed  ConnectionStatus = 4
	StatusConnectionLost ConnectionStatus = 5
	StatusDisconnected   ConnectionStatus = 6

	EncTypeTKIP EncryptionType = 2
	EncTypeCCMP EncryptionType = 4
	EncTypeWEP  EncryptionType = 5
	EncTypeNone EncryptionType = 7
	EncTypeAuto EncryptionType = 8

	TCPStateClosed      = 0
	TCPStateListen      = 1
	TCPStateSynSent     = 2
	TCPStateSynRcvd     = 3
	TCPStateEstablished = 4
	TCPStateFinWait1    = 5
	TCPStateFinWait2    = 6
	TCPStateCloseWait   = 7
	TCPStateClosing     = 8
	TCPStateLastACK     = 9
	TCPStateTimeWait    = 10

	FlagCmd   = 0
	FlagReply = 1 << 7
	FlagData  = 0x40

	NinaCmdPos      = 1
	NinaParamLenPos = 2

	CmdStart = 0xE0
	CmdEnd   = 0xEE
	CmdErr   = 0xEF

	CmdSetNet          = 0x10
	CmdSetPassphrase   = 0x11
	CmdSetKey          = 0x12
	CmdSetIPConfig     = 0x14
	CmdSetDNSConfig    = 0x15
	CmdSetHostname     = 0x16
	CmdSetPowerMode    = 0x17
	CmdSetAPNet        = 0x18
	CmdSetAPPassphrase = 0x19
	CmdSetDebug        = 0x1A
	CmdGetTemperature  = 0x1B
	CmdGetReasonCode   = 0x1F

	CmdGetConnStatus     = 0x20
	CmdGetIPAddr         = 0x21
	CmdGetMACAddr        = 0x22
	CmdGetCurrSSID       = 0x23
	CmdGetCurrBSSID      = 0x24
	CmdGetCurrRSSI       = 0x25
	CmdGetCurrEncrType   = 0x26
	CmdScanNetworks      = 0x27
	CmdStartServerTCP    = 0x28
	CmdGetStateTCP       = 0x29
	CmdDataSentTCP       = 0x2A
	CmdAvailDataTCP      = 0x2B
	CmdGetDataTCP        = 0x2C
	CmdStartClientTCP    = 0x2D
	CmdStopClientTCP     = 0x2E
	CmdGetClientStateTCP = 0x2F
	CmdDisconnect        = 0x30
	CmdGetIdxRSSI        = 0x32
	CmdGetIdxEncrType    = 0x33
	CmdReqHostByName     = 0x34
	CmdGetHostByName     = 0x35
	CmdStartScanNetworks = 0x36
	CmdGetFwVersion      = 0x37
	CmdSendDataUDP       = 0x39
	CmdGetRemoteData     = 0x3A
	CmdGetTime           = 0x3B
	CmdGetIdxBSSID       = 0x3C
	CmdGetIdxChannel     = 0x3D
	CmdPing              = 0x3E
	CmdGetSocket         = 0x3F

	// All command with DATA_FLAG 0x40 send a 16bit Len
	CmdSendDataTCP   = 0x44
	CmdGetDatabufTCP = 0x45
	CmdInsertDataBuf = 0x46

	// regular format commands
	CmdSetPinMode      = 0x50
	CmdSetDigitalWrite = 0x51
	CmdSetAnalogWrite  = 0x52

	ErrTimeoutChipReady  Error = 0x01
	ErrTimeoutChipSelect Error = 0x02
	ErrCheckStartCmd     Error = 0x03
	ErrWaitRsp           Error = 0x04
	ErrUnexpectedLength  Error = 0xE0
	ErrNoParamsReturned  Error = 0xE1
	ErrIncorrectSentinel Error = 0xE2
	ErrCmdErrorReceived  Error = 0xEF
	ErrNotImplemented    Error = 0xF0
	ErrUnknownHost       Error = 0xF1
	ErrSocketAlreadySet  Error = 0xF2
	ErrConnectionTimeout Error = 0xF3
	ErrNoData            Error = 0xF4
	ErrDataNotWritten    Error = 0xF5
	ErrCheckDataError    Error = 0xF6
	ErrBufferTooSmall    Error = 0xF7
	ErrNoSocketAvail     Error = 0xFF

	NoSocketAvail uint8 = 0xFF
)
View Source
const (
	ProtoModeTCP = iota
	ProtoModeUDP
	ProtoModeTLS
	ProtoModeMul
)
View Source
const (
	ReadBufferSize = 128
)

Variables

View Source
var (
	ErrPinNoDevice = errors.New("wifinina pin: device not set")
)

Functions

This section is empty.

Types

type ConnectionStatus

type ConnectionStatus uint8

func (ConnectionStatus) String

func (c ConnectionStatus) String() string

type Device

type Device struct {
	SPI   drivers.SPI
	CS    machine.Pin
	ACK   machine.Pin
	GPIO0 machine.Pin
	RESET machine.Pin
	// contains filtered or unexported fields
}

func New

func New(bus drivers.SPI, csPin, ackPin, gpio0Pin, resetPin machine.Pin) *Device

New returns a new Wifinina device.

func (*Device) AnalogWrite

func (d *Device) AnalogWrite(pin uint8, value uint8) error

func (*Device) CheckDataSent

func (d *Device) CheckDataSent(sock uint8) (bool, error)

func (*Device) Configure

func (d *Device) Configure()

func (*Device) ConnectSSLSocket

func (d *Device) ConnectSSLSocket(addr, portStr string) error

func (*Device) ConnectTCPSocket

func (d *Device) ConnectTCPSocket(addr, portStr string) error

func (*Device) ConnectToAccessPoint

func (d *Device) ConnectToAccessPoint(ssid, pass string, timeout time.Duration) error

func (*Device) ConnectUDPSocket

func (d *Device) ConnectUDPSocket(addr, portStr, lportStr string) (err error)

func (*Device) DigitalWrite

func (d *Device) DigitalWrite(pin uint8, value uint8) error

func (*Device) Disconnect

func (d *Device) Disconnect() error

func (*Device) DisconnectSocket

func (d *Device) DisconnectSocket() error

func (*Device) GetClientIP

func (d *Device) GetClientIP() (string, error)

func (*Device) GetClientState

func (d *Device) GetClientState(sock uint8) (uint8, error)

func (*Device) GetConnectionStatus

func (d *Device) GetConnectionStatus() (ConnectionStatus, error)

func (*Device) GetCurrentBSSID

func (d *Device) GetCurrentBSSID() (MACAddress, error)

func (*Device) GetCurrentEncryptionType

func (d *Device) GetCurrentEncryptionType() (EncryptionType, error)

func (*Device) GetCurrentRSSI

func (d *Device) GetCurrentRSSI() (int32, error)

func (*Device) GetCurrentSSID

func (d *Device) GetCurrentSSID() (string, error)

func (*Device) GetDNS

func (d *Device) GetDNS(domain string) (string, error)

func (*Device) GetDataBuf

func (d *Device) GetDataBuf(sock uint8, buf []byte) (int, error)

func (*Device) GetFwVersion

func (d *Device) GetFwVersion() (string, error)

func (*Device) GetHostByName

func (d *Device) GetHostByName(hostname string) (IPAddress, error)

func (*Device) GetIP

func (d *Device) GetIP() (ip, subnet, gateway IPAddress, err error)

func (*Device) GetMACAddress

func (d *Device) GetMACAddress() (MACAddress, error)

func (*Device) GetNetworkBSSID

func (d *Device) GetNetworkBSSID(idx int) (MACAddress, error)

func (*Device) GetNetworkChannel

func (d *Device) GetNetworkChannel(idx int) (uint8, error)

func (*Device) GetNetworkEncrType

func (d *Device) GetNetworkEncrType(idx int) (EncryptionType, error)

func (*Device) GetNetworkRSSI

func (d *Device) GetNetworkRSSI(idx int) (int32, error)

func (*Device) GetNetworkSSID

func (d *Device) GetNetworkSSID(idx int) string

func (*Device) GetReasonCode

func (d *Device) GetReasonCode() (uint8, error)

func (*Device) GetSocket

func (d *Device) GetSocket() (uint8, error)

func (*Device) GetTemperature

func (d *Device) GetTemperature() (float32, error)

func (*Device) GetTime

func (d *Device) GetTime() (uint32, error)

GetTime is the time as a Unix timestamp

func (*Device) InsertDataBuf

func (d *Device) InsertDataBuf(buf []byte, sock uint8) (bool, error)

InsertDataBuf adds data to the buffer used for sending UDP data

func (*Device) IsConnected

func (d *Device) IsConnected() (bool, error)

func (*Device) IsSocketDataAvailable

func (d *Device) IsSocketDataAvailable() bool

IsSocketDataAvailable returns of there is socket data available

func (*Device) PinMode

func (d *Device) PinMode(pin uint8, mode uint8) error

func (*Device) Ping

func (d *Device) Ping(ip IPAddress, ttl uint8) int16

func (*Device) ReadSocket

func (d *Device) ReadSocket(b []byte) (n int, err error)

func (*Device) Response

func (d *Device) Response(timeout int) ([]byte, error)

func (*Device) ScanNetworks

func (d *Device) ScanNetworks() (uint8, error)

func (*Device) SendData

func (d *Device) SendData(buf []byte, sock uint8) (uint16, error)

func (*Device) SendUDPData

func (d *Device) SendUDPData(sock uint8) (bool, error)

SendUDPData sends the data previously added to the UDP buffer

func (*Device) SetDNS

func (d *Device) SetDNS(which uint8, dns1 uint32, dns2 uint32) error

func (*Device) SetDebug

func (d *Device) SetDebug(on bool) error

func (*Device) SetHostname

func (d *Device) SetHostname(hostname string) error

func (*Device) SetIP

func (d *Device) SetIP(which uint8, ip uint32, gw uint32, subnet uint32) error

func (*Device) SetKey

func (d *Device) SetKey(ssid string, index uint8, key string) error

func (*Device) SetNetwork

func (d *Device) SetNetwork(ssid string) error

func (*Device) SetNetworkForAP

func (d *Device) SetNetworkForAP(ssid string) error

func (*Device) SetPassphrase

func (d *Device) SetPassphrase(ssid string, passphrase string) error

func (*Device) SetPassphraseForAP

func (d *Device) SetPassphraseForAP(ssid string, passphrase string) error

func (*Device) SetPowerMode

func (d *Device) SetPowerMode(mode uint8) error

func (*Device) StartClient

func (d *Device) StartClient(hostname string, addr uint32, port uint16, sock uint8, mode uint8) error

func (*Device) StartScanNetworks

func (d *Device) StartScanNetworks() (uint8, error)

func (*Device) StartServer

func (d *Device) StartServer(port uint16, sock uint8, mode uint8) error

func (*Device) StartSocketSend

func (d *Device) StartSocketSend(size int) error

func (*Device) StopClient

func (d *Device) StopClient(sock uint8) error

func (*Device) Write

func (d *Device) Write(b []byte) (n int, err error)

type EncryptionType

type EncryptionType uint8

func (EncryptionType) String

func (e EncryptionType) String() string

type Error

type Error uint8

func (Error) Error

func (err Error) Error() string

type IPAddress

type IPAddress string // TODO: does WiFiNINA support ipv6???

func ParseIPv4

func ParseIPv4(s string) (IPAddress, error)

func (IPAddress) AsUint32

func (addr IPAddress) AsUint32() uint32

func (IPAddress) String

func (addr IPAddress) String() string

type MACAddress

type MACAddress uint64

func (MACAddress) String

func (addr MACAddress) String() string

type Pin

type Pin uint8

func (Pin) Configure

func (p Pin) Configure(config PinConfig) error

func (Pin) High

func (p Pin) High() error

func (Pin) Low

func (p Pin) Low() error

func (Pin) Set

func (p Pin) Set(high bool) error

type PinConfig

type PinConfig struct {
	Mode PinMode
}

type PinMode

type PinMode uint8
const (
	PinInput PinMode = iota
	PinOutput
	PinInputPullup
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL