cyw43439

README

cyw43439

Driver for the Wifi+bluetooth integrated circuit on the pico.

Examples

To run the blinky example:

tinygo flash -target=pico -stack-size=8kb -monitor  ./examples/blinky

To run Wifi examples you must first set your wifi credentials:

1. Clone this repository

2. Rename examples/common/secrets.go.template to have the .go extension and edit the contents with ssid and pass strings set to your WIFI SSID and Password, respecively. If pass is not set then an open network is assumed.

3. Run any of the examples in the examples directory

   Example of how to run the DHCP example:

   tinygo flash -target=pico -stack-size=8kb -monitor  ./examples/dhcp
   

Debugging and heap allocations

The examples use the soypat/seqs networking stack library. One can enable heap debugging by using the debugheaplog build tag:

Example:

tinygo flash -target=pico -stack-size=8kb -monitor -tags=debugheaplog  ./examples/dhcp

This will use a simpler logger implementation within the seqs package that avoids all allocations and will also log heap increments on lines starting with the [ALLOC] text.

Contributions

PRs welcome! Please read most recent developments on this issue before contributing.

FYI

• RP2040 datasheet.

• CYW43439 datasheet

• Pico SDK github repo

  • pico_w.h

  • cyw43_driver/cyw43_bus_pio_spi.c: Core driver for interfacing directly with the CYW43439. This is what this repo will target in the port.

  • pico_cyw43_arch: Architecture for integrating the CYW43 driver (for the wireless on Pico W) and lwIP (for TCP/IP stack) into the SDK. It is also necessary for accessing the on-board LED on Pico W.

    • pico_cyw43_arch/include/pico/cyw43_arch.h: Headers for the architecture driver. Has a very complete comment introducing the architecture library.

Peripheral side APIs

Examples:

• APA102 addressable LED strip.
  • Here is the Go driver: well programmed and simple. Follows good practices like storing buffers in-struct as arrays (buf field) to avoid heap allocations and encouraging better CPU memory access patterns.
  • I could not find a high quality C or C++ driver, there seems to be a different driver for each microcontroller. Here's an ESP8266 driver for the APA102 which seemed reasonably well programmed.
• Wifinina SPI driver for ESP32 wifi with TCP/IP.

Microcontroller side APIs

The CYW43439 driver will have minimal microcontroller side API code, though it does not hurt to read up a little bit on it.

It may be of interest to the reader to know a bit of how one ports microcontroller specific code from C to Go. This code is characterized by the heavy use of volatile memory registers and data structures that map peripheral functionality directly to these segments of volatile memory.

For the case of the RP2040 (the raspberry pi's pico microcontroller) one can find most of microcontroller specific code in the TinyGo machine package- Look for filenames starting with machine_rp2040. In the author's opinion one of the cleanest peripheral API's is the RP2040's I2C driver, which you may find in machine_rp2040_i2c.go in said package.

The C counterparts are in the pico-sdk's rp2_common directory. The I2C counterpart includes the header file with function signatures and type definitions... and more interestingly, the actual code under hardware_i2c/i2c.c. Do note the port is almost direct. Some functions have been grouped differently and have slightly different signatures in the Go version.

The PWM API is much more closely matched between the C and Go version, albeit much simpler.

Go and TinyGo Ethernet/IP/TCP stack comparisons

Install stringer command

go install golang.org/x/tools/cmd/stringer@latest

Documentation

Index

• Constants
• Variables
• func GetCLM(firmware []byte) []byte
• type Config
  • func DefaultBluetoothConfig() Config
  • func DefaultWifiBluetoothConfig() Config
  • func DefaultWifiConfig() Config
• type Device
  • func New(pwr, cs outputPin, spi cmdBus) *Device
  • func (d *Device) BufferedHCI() int
  • func (d *Device) GPIOSet(wlGPIO uint8, value bool) (err error)
  • func (d *Device) HCIReadWriter() (interface{ ... }, error)
  • func (d *Device) HardwareAddr6() ([6]byte, error)
  • func (d *Device) Init(cfg Config) (err error)
  • func (d *Device) IsLinkUp() bool
  • func (d *Device) JoinWPA2(ssid, pass string) error
  • func (d *Device) MACAs6() [6]byte
  • func (d *Device) MTU() int
  • func (d *Device) NetFlags() (flags net.Flags)
  • func (d *Device) PollOne() (bool, error)
  • func (d *Device) ReadHCI(b []byte) (int, error)
  • func (d *Device) RecvEthHandle(handler func(pkt []byte) error)
  • func (d *Device) Reset()
  • func (d *Device) SendEth(pkt []byte) error
  • func (d *Device) SetLogger(l *slog.Logger)
  • func (d *Device) StartAP(ssid, pass string, channel uint8) error
  • func (d *Device) TryPoll() (gotPacket bool, err error)
  • func (d *Device) WriteHCI(b []byte) (int, error)
• type Function
  • func (f Function) String() (s string)
• type Interrupts
  • func (Int Interrupts) IsBusOverflowedOrUnderflowed() bool
  • func (Int Interrupts) IsDataUnavailable() bool
  • func (Int Interrupts) IsF2Available() bool
  • func (Int Interrupts) String() (s string)
• type Status
  • func (s Status) DataUnavailable() bool
  • func (s Status) F2Interrupt() bool
  • func (s Status) F2PacketAvailable() bool
  • func (s Status) F2PacketLength() uint16
  • func (s Status) F2RxReady() bool
  • func (s Status) F3PacketAvailable() bool
  • func (s Status) F3PacketLength() uint16
  • func (s Status) F3RxReady() bool
  • func (s Status) GSPIPacketAvailable() bool
  • func (s Status) HostCommandDataError() bool
  • func (s Status) IsOverflow() bool
  • func (s Status) IsUnderflow() bool
  • func (s Status) String() (str string)

Constants

const MTU = 2048 - mtuPrefix

Variables

var ErrDataNotAvailable = errors.New("requested data not available")

Functions

func GetCLM

func GetCLM(firmware []byte) []byte

Types

type Config

type Config struct {
	Firmware string
	CLM      string
	Logger   *slog.Logger
	// contains filtered or unexported fields
}

func DefaultBluetoothConfig

func DefaultBluetoothConfig() Config

func DefaultWifiBluetoothConfig

func DefaultWifiBluetoothConfig() Config

func DefaultWifiConfig

func DefaultWifiConfig() Config

type Device

type Device struct {
	// contains filtered or unexported fields
}

type OutputPin func(bool)

func New

func New(pwr, cs outputPin, spi cmdBus) *Device

func (*Device) BufferedHCI

func (d *Device) BufferedHCI() int

BufferedHCI returns amounts of HCI bytes stored inside CYW43439 internal ring buffer.

func (*Device) GPIOSet

func (d *Device) GPIOSet(wlGPIO uint8, value bool) (err error)

func (*Device) HCIReadWriter

func (d *Device) HCIReadWriter() (interface {
	io.ReadWriter
	Buffered() int
}, error)

HCIReaderWriter returns a io.ReadWriter interface which wraps the BufferedHCI, WriteHCI and ReadHCI methods.

func (*Device) HardwareAddr6

func (d *Device) HardwareAddr6() ([6]byte, error)

HardwareAddr6 returns the device's 6-byte MAC address.

func (*Device) Init

func (d *Device) Init(cfg Config) (err error)

func (*Device) IsLinkUp

func (d *Device) IsLinkUp() bool

IsLinkUp returns true if the wifi connection is up.

func (*Device) JoinWPA2

func (d *Device) JoinWPA2(ssid, pass string) error

func (*Device) MACAs6

func (d *Device) MACAs6() [6]byte

MACAs6

Deprecated: Use HardwareAddr6() instead.

func (*Device) MTU

func (d *Device) MTU() int

MTU (maximum transmission unit) returns the maximum amount of bytes that can be sent in a single ethernet frame in a call to SendEth.

func (*Device) NetFlags

func (d *Device) NetFlags() (flags net.Flags)

NetFlags returns the current network flags for the device.

func (*Device) PollOne

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

PollOne attempts to read a packet from the device. Returns true if a packet was read, false if no packet was available.

func (*Device) ReadHCI

func (d *Device) ReadHCI(b []byte) (int, error)

WriteHCI reads from HCI ring buffer internal to the CYW43439. Used for bluetooth.

func (*Device) RecvEthHandle

func (d *Device) RecvEthHandle(handler func(pkt []byte) error)

RecvEthHandle sets handler for receiving Ethernet pkt If set to nil then incoming packets are ignored.

func (*Device) Reset

func (d *Device) Reset()

Reset power-cycles the CYW43439 by turning WLREGON off and on and waiting the suggested amount of time for SPI bus to initialize. To use Device again Init should be called after a Reset.

func (*Device) SendEth

func (d *Device) SendEth(pkt []byte) error

SendEth sends an Ethernet packet over the current interface.

func (*Device) SetLogger

func (d *Device) SetLogger(l *slog.Logger)

SetLogger sets the logger for the device. If nil logging is disabled.

func (*Device) StartAP

func (d *Device) StartAP(ssid, pass string, channel uint8) error

func (*Device) TryPoll

func (d *Device) TryPoll() (gotPacket bool, err error)

TryPoll

Deprecated: Use PollOne instead.

func (*Device) WriteHCI

func (d *Device) WriteHCI(b []byte) (int, error)

WriteHCI sends a HCI packet over the CYW43439's interface. Used for bluetooth.

type Function

type Function uint32

const (
	// All SPI-specific registers.
	FuncBus Function = 0b00
	// Registers and memories belonging to other blocks in the chip (64 bytes max).
	FuncBackplane Function = 0b01
	// DMA channel 1. WLAN packets up to 2048 bytes.
	FuncDMA1 Function = 0b10
	FuncWLAN          = FuncDMA1
	// DMA channel 2 (optional). Packets up to 2048 bytes.
	FuncDMA2 Function = 0b11
)

func (Function) String

func (f Function) String() (s string)

type Interrupts

type Interrupts uint16

func (Interrupts) IsBusOverflowedOrUnderflowed

func (Int Interrupts) IsBusOverflowedOrUnderflowed() bool

func (Interrupts) IsDataUnavailable

func (Int Interrupts) IsDataUnavailable() bool

func (Interrupts) IsF2Available

func (Int Interrupts) IsF2Available() bool

func (Interrupts) String

func (Int Interrupts) String() (s string)

type Status

type Status uint32

Status supports status notification to the host after a read/write transaction over gSPI. This status notification provides information about packet errors, protocol errors, available packets in the RX queue, etc. The status information helps reduce the number of interrupts to the host. The status-reporting feature can be switched off using a register bit, without any timing overhead.

func (Status) DataUnavailable

func (s Status) DataUnavailable() bool

DataUnavailable returns true if requested read data is unavailable.

func (Status) F2Interrupt

func (s Status) F2Interrupt() bool

F2Interrupt returns true if F2 channel interrupt set.

func (Status) F2PacketAvailable

func (s Status) F2PacketAvailable() bool

F2PacketAvailable returns true if Packet is available/ready in F2 TX FIFO.

func (Status) F2PacketLength

func (s Status) F2PacketLength() uint16

F2PacketAvailable returns F2 packet length.

func (Status) F2RxReady

func (s Status) F2RxReady() bool

F2RxReady returns true if F2 FIFO is ready to receive data (FIFO empty).

func (Status) F3PacketAvailable

func (s Status) F3PacketAvailable() bool

F3PacketAvailable returns true if Packet is available/ready in F3 TX FIFO.

func (Status) F3PacketLength

func (s Status) F3PacketLength() uint16

F3PacketAvailable returns F3 packet length.

func (Status) F3RxReady

func (s Status) F3RxReady() bool

F3RxReady returns true if F3 FIFO is ready to receive data (FIFO empty).

func (Status) GSPIPacketAvailable

func (s Status) GSPIPacketAvailable() bool

GSPIPacketAvailable notifies there is a packet available over gSPI.

func (Status) HostCommandDataError

func (s Status) HostCommandDataError() bool

HostCommandDataError TODO document.

func (Status) IsOverflow

func (s Status) IsOverflow() bool

IsOverflow returns true if FIFO overflow occurred due to current (F1, F2, F3) write command.

func (Status) IsUnderflow

func (s Status) IsUnderflow() bool

IsUnderflow returns true if FIFO underflow occurred due to current (F2, F3) read command.

func (Status) String

func (s Status) String() (str string)