# Ethernet for CircuitPython with Wiznet5K
## Overview
Wireless is wonderful, but sometimes you want the strong reliability of a wired connection. If your project is going to be part of a permanent installation, you'll want to add ethernet networking to your project.
**Ethernet is incredibly easy to use** - there's no network configuration or device pairing. **Just plug a standard Ethernet cable into an Ethernet FeatherWing or Ethernet Shield and use the [CircuitPython Wiznet5k](https://github.com/adafruit/Adafruit_CircuitPython_Wiznet5k/) library for quick and reliable, networking.**
- **If you'd like to learn more about the Ethernet standard** -[ check out its section in the All The Internet of Things: Transports guide](https://learn.adafruit.com/alltheiot-transports/ethernet).
**We've built a module for CircuitPython compatible with[WIZnet 5k-series TCP/IP Ethernet controllers](https://docs.wiznet.io/Product/iEthernet/W5500/overview) to quickly get your projects online.** Seconds after connecting, the module will handle performing the DHCP setup for you. You may also supply this module with a statically-assigned network configuration.
In this guide, you will set up your CircuitPython hardware and connect to the internet. We've included code walkthrough portions of this guide, so you can roll your own Ethernet-connected IoT CircuitPython project.
Warning:
## Parts
The Ethernet FeatherWing is plug-and-play compatible with CircuitPython boards which use the [Feather pinout](https://www.adafruit.com/categories/835), such as the [Adafruit Feather M4 Express](https://www.adafruit.com/product/3857).
### Adafruit Ethernet FeatherWing
[Adafruit Ethernet FeatherWing](https://www.adafruit.com/product/3201)
Wireless is wonderful, but sometimes you want the strong reliability of a wire. If your Feather board is going to be part of a permanent installation, this **Ethernet FeatherWing** will let you add quick and easy wired Internet. Just plug in a standard
In Stock
[Buy Now](https://www.adafruit.com/product/3201)
[Related Guides to the Product](https://learn.adafruit.com/products/3201/guides)
The Ethernet Shield is compatible with development boards which use the pinout such as the [Adafruit Metro M4](https://www.adafruit.com/product/3382) and the [Adafruit Grand Central M4 Express](https://www.adafruit.com/product/4064). The shield includes a RJ45 Ethernet port and a microSD card holder for storing and reading data.
### Part: Ethernet Cable, 5ft
quantity: 1
Ethernet Cable - 5 ft long
[Ethernet Cable, 5ft](https://www.adafruit.com/product/994)
### Part: Ethernet Cable, 10ft
quantity: 1
Ethernet Cable - 10 ft long
[Ethernet Cable, 10ft](https://www.adafruit.com/product/730)
### Part: PoE Splitter with MicroUSB Plug
quantity: 1
PoE Splitter with MicroUSB Plug - Isolated 12W - 5V 2.4 Amp
[PoE Splitter with MicroUSB Plug](https://www.adafruit.com/product/3785)
### Part: Passive PoE Injector Cable Set
quantity: 1
Passive PoE Injector Cable Set
[Passive PoE Injector Cable Set](https://www.adafruit.com/product/435)
# Ethernet for CircuitPython with Wiznet5K
## CircuitPython Setup
## CircuitPython Installation
Some CircuitPython compatible boards come with CircuitPython installed. Others are _CircuitPython-ready_, but need to have it installed. As well, you may want to update the version of CircuitPython already installed on your board. The steps are the same for installing and updating.
- To **install (or update) your CircuitPython board**, [follow this page and come back here when you've successfully installed (or updated) CircuitPython.](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython)
## Install the Mu Editor
This guide requires you to edit and interact with CircuitPython code. While you can use any text editor of your choosing, **Mu** is a simple code editor that works with the Adafruit CircuitPython boards. It's written in Python and works on Windows, MacOS, Linux and Raspberry Pi. The serial console is built right in, so you get immediate feedback from your board's serial output!
Before proceeding, if you'd like to use Mu, **click the button below to install the Mu Editor**. There are versions for PC, mac, and Linux.
[Install Mu Editor](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor)
## CircuitPython Library Installation
First make sure you are running the [latest version of Adafruit CircuitPython](https://circuitpython.org/board/pyportal/) for your board.
Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from [Adafruit's CircuitPython library bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle) matching your version of CircuitPython. The [Wiznet5k Library r](https://github.com/adafruit/Adafruit_CircuitPython_Wiznet5k)equires at least CircuitPython version 4.0.0.
Before continuing, make sure your board's **lib** folder has at least the following files and folders ** ** copied over:
- **adafruit\_wiznet5k**
- **adafruit\_bus\_device**
- **adafruit\_requests.mpy**
Once all the files are copied, your **CIRCUITPY** drive should look like the following screenshot:
# Ethernet for CircuitPython with Wiznet5K
## Usage
## Connect Ethernet Cable
Make sure you have your Ethernet FeatherWing or Ethernet Shield firmly plugged into your hardware, and an Ethernet cable connected to your router or switch.
## Code Usage
Copy the following code to the **code.py** file on your microcontroller.
https://github.com/adafruit/Adafruit_CircuitPython_Wiznet5k/blob/main/examples/wiznet5k_simpletest.py
**Save the code.py file** and **open the REPL**.
**If you don't get an IP address** , check you have a green link light, and that your Ethernet is going out to an internet connected router. You may also have to set up the MAC address to allow it access, check with your system admin if you're not sure.
In order, the example code:
Initializes the Ethernet chipset over SPI using the SPI port and the CS pin.
```python
cs = digitalio.DigitalInOut(board.D10)
spi_bus = busio.SPI(board.SCK, MOSI=board.MOSI, MISO=board.MISO)
eth = WIZNET5K(spi_bus, cs)
```
Tells the `requests` library the socket, and interface we'll be using. The interface is set to an `eth` object. This is a little bit of a hack, but it lets us use `requests` like CPython does.
```python
requests.set_socket(socket, eth)
```
Verifies the Ethernet hardware was found, checks the chip version and MAC address.
```python
print("Chip Version:", eth.chip)
print("MAC Address:", [hex(i) for i in eth.mac_address])
```
Prints out the local IP and attempts to perform an IP address lookup for adafruit.com.
```python
print("My IP address is:", eth.pretty_ip(eth.ip_address))
print("IP lookup adafruit.com: %s" %eth.pretty_ip(eth.get_host_by_name("adafruit.com")))
```
OK now we're getting to the really interesting part. With a SAMD51 or other large-RAM (well, over 32 KB) device, we can do a lot of neat tricks. Like, for example, we can implement an interface a lot like [requests](http://docs.python-requests.org/en/master/) - which makes getting data _really really easy_
To read in all the text from a web URL, call `requests.get` -
```python
print("Fetching text from", TEXT_URL)
r = requests.get(TEXT_URL)
print('-'*40)
print(r.text)
print('-'*40)
r.close()
```
Or, if the data is in structured JSON, you can get the json pre-parsed into a Python dictionary that can be easily queried or traversed. (Again, only for nRF52840, M4 and other high-RAM boards)
```python
print()
print("Fetching json from", JSON_URL)
r = requests.get(JSON_URL)
print('-'*40)
print(r.json())
print('-'*40)
r.close()
```
## Manual Network Configuration
The Wiznet5k library automatically takes care of DHCP and DNS configuration, so you can get your project online quickly. However, there are cases where a network administrator will provide you with an IP address or you may need to manually configure the interface.
This code performs the same Ethernet simpletest as the above section, but allows you to configure your network interface.
https://github.com/adafruit/Adafruit_CircuitPython_Wiznet5k/blob/main/examples/wiznet5k_simpletest_manual_network.py
You will need to manually set your network configuration:
- **Set** `IP_ADDRESS` to your desired IP address.
- **Set** `SUBNET_MASK` to the router's subnet mask
- **Set** `GATEWAY_ADDRESS` to the router's IP address.
- **Set** `DNS_SERVER` to the DNS server you'd like to use. We're using 8.8.8.8 which is Google's Public DNS.
```python
# Setup your network configuration below
IP_ADDRESS = (192, 168, 10, 1)
SUBNET_MASK = (255, 255, 0, 0)
GATEWAY_ADDRESS = (192, 168, 0, 1)
DNS_SERVER = (8, 8, 8, 8)
```
When the Ethernet interface is initialized, we'll disable the automatic DHCP process.
```python
# Initialize ethernet interface without DHCP
eth = WIZNET5K(spi_bus, cs, is_dhcp=False)
```
Then, we'll set up the network configuration by passing the `ifconfig` property a tuple containing the IP address, subnet mask, gateway address and DNS server.
```python
# Set network configuration
eth.ifconfig = (IP_ADDRESS, SUBNET_MASK, GATEWAY_ADDRESS, DNS_SERVER)
```
## Troubleshooting
If you are experiencing issues, customers have found success with connecting the RESET pin of the FeatherWing to a DigitalIO pin on their Feather.
For example, for a Raspberry Pi Pico, you would declare a `reset` pin and then pass it to the `WIZNET5K` class:
```auto
...
reset = digitalio.DigitalInOut(board.GP20)
eth = WIZNET5K(spi_bus, cs, reset, is_dhcp=False)
```
# Ethernet for CircuitPython with Wiznet5K
## Usage with Requests
Danger:
We've written a [requests-like](https://2.python-requests.org/en/master/) library for web interfacing named [Adafruit\_CircuitPython\_Requests](https://github.com/adafruit/Adafruit_CircuitPython_Requests). This library allows you to send HTTP/1.1 requests without "crafting" them and provides helpful methods for parsing the response from the server.
https://github.com/adafruit/Adafruit_CircuitPython_Requests/blob/main/examples/wiznet5k/requests_wiznet5k_simpletest.py
The code initializes a request object using a `socket` and the `requests` interface.
## HTTP GET with Requests
The code makes a HTTP GET request to Adafruit's WiFi testing website - [http://wifitest.adafruit.com/testwifi/index.html](http://wifitest.adafruit.com/testwifi/index.html).
To do this, we'll pass the URL into `requests.get()`. We're also going to save the response _from_ the server into a variable named `response`. The call to `requests.get()` is wrapped in a loop which retries 3 times in the event of a failed request.
While we requested data from the server, we'd like to see what the server responded with. Since we already saved the server's `response`, we can read it back. Luckily for us, **requests automatically decodes the server's response into human-readable text. Y** ou can read it back by calling `response.text`.
Lastly, we'll perform a bit of cleanup by calling `response.close()`. This closes, deletes, and collect's the response's data.
```python
print("Fetching text from %s"%TEXT_URL)
while not response:
try:
response = requests.get(TEXT_URL)
failure_count = 0
except AssertionError as error:
print("Request failed, retrying...\n", error)
failure_count += 1
if failure_count >= attempts:
raise AssertionError("Failed to resolve hostname, \
please check your router's DNS configuration.")
continue
print('-'*40)
print("Text Response: ", response.text)
print('-'*40)
response.close()
```
While some servers respond with text, some respond with json-formatted data consisting of attribute–value pairs.
**CircuitPython\_Requests can convert a JSON-formatted response from a server into a CPython `dict` object.**
We can also fetch and parse **json** data. We'll send a HTTP get to a url we know returns a json-formatted response (instead of text data).
**Then, the code calls `response.json()` to convert the response to a CPython `dict`. **
```python
print("Fetching JSON data from %s"%JSON_GET_URL)
while not response:
try:
response = requests.get(JSON_GET_URL)
failure_count = 0
except AssertionError as error:
print("Request failed, retrying...\n", error)
failure_count += 1
if failure_count >= attempts:
raise AssertionError("Failed to resolve hostname, \
please check your router's DNS configuration.")
continue
print('-'*40)
print("JSON Response: ", response.json())
print('-'*40)
response.close()
```
## HTTP POST with Requests
Requests can also POST data to a server by calling the **`requests.post`** method, passing it a ** `data`** value **.**
```python
data = '31F'
print("POSTing data to {0}: {1}".format(JSON_POST_URL, data))
while not response:
try:
response = requests.post(JSON_POST_URL, data=data)
failure_count = 0
except AssertionError as error:
print("Request failed, retrying...\n", error)
failure_count += 1
if failure_count >= attempts:
raise AssertionError("Failed to resolve hostname, \
please check your router's DNS configuration.")
continue
print('-'*40)
json_resp = response.json()
# Parse out the 'data' key from json_resp dict.
print("Data received from server:", json_resp['data'])
print('-'*40)
response.close()
```
You can also post json-formatted data to a server by passing **`json_data`** into the **`requests.post`** method.
```python
json_data = {"Date" : "July 25, 2019"}
print("POSTing data to {0}: {1}".format(JSON_POST_URL, json_data))
while not response:
try:
response = requests.post(JSON_POST_URL, json=json_data)
failure_count = 0
except AssertionError as error:
print("Request failed, retrying...\n", error)
failure_count += 1
if failure_count >= attempts:
raise AssertionError("Failed to resolve hostname, \
please check your router's DNS configuration.")
continue
print('-'*40)
json_resp = response.json()
# Parse out the 'json' key from json_resp dict.
print("JSON Data received from server:", json_resp['json'])
print('-'*40)
response.close()
```
# Ethernet for CircuitPython with Wiznet5K
## Usage with MiniMQTT
# Ethernet for CircuitPython with Wiznet5K
## Python Docs
## Featured Products
### Adafruit Ethernet FeatherWing
[Adafruit Ethernet FeatherWing](https://www.adafruit.com/product/3201)
Wireless is wonderful, but sometimes you want the strong reliability of a wire. If your Feather board is going to be part of a permanent installation, this **Ethernet FeatherWing** will let you add quick and easy wired Internet. Just plug in a standard
In Stock
[Buy Now](https://www.adafruit.com/product/3201)
[Related Guides to the Product](https://learn.adafruit.com/products/3201/guides)
### Ethernet Shield for Arduino - W5500 Chipset
[Ethernet Shield for Arduino - W5500 Chipset](https://www.adafruit.com/product/2971)
The W5500 Ethernet Shield for Arduino from Seeed Studio is a great way to set up your projects with internet connectivity with just a single chip. Similar to the[Arduino Ethernet Shield](https://www.adafruit.com/product/201), but with a newer chipset, this ethernet shield...
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/2971)
[Related Guides to the Product](https://learn.adafruit.com/products/2971/guides)
### Ethernet Cable - 5 ft long
[Ethernet Cable - 5 ft long](https://www.adafruit.com/product/994)
We have so many Internet-connected goodies in the shop, we figured it's time to carry a cable so you can easily connect them up! This cable is 5 feet long, comes in Adafruit black and has all 8 wires installed. Perfect for use with the
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/994)
[Related Guides to the Product](https://learn.adafruit.com/products/994/guides)
### Ethernet Cable - 10 ft long
[Ethernet Cable - 10 ft long](https://www.adafruit.com/product/730)
We have so many Internet-connected goodies in the shop, we figured it's time to carry a cable so you can easily connect them up! This cable is 10 feet long, black and has all 8 wires installed. Perfect for use with the [BeagleBone](http://www.adafruit.com/products/513),
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/730)
[Related Guides to the Product](https://learn.adafruit.com/products/730/guides)
### PoE Splitter with MicroUSB Plug - Isolated 12W - 5V 2.4 Amp
[PoE Splitter with MicroUSB Plug - Isolated 12W - 5V 2.4 Amp](https://www.adafruit.com/product/3785)
Power over Ethernet (PoE) splitters can make your project wiring a breeze - and best of all they work to connect any 802.3af-capable router to any Ethernet device, _even if it doesn't natively support PoE!_ The splitter takes a unified PoE signal (data and power) from one RJ-45...
In Stock
[Buy Now](https://www.adafruit.com/product/3785)
[Related Guides to the Product](https://learn.adafruit.com/products/3785/guides)
### Adafruit Feather M4 Express - Featuring ATSAMD51
[Adafruit Feather M4 Express - Featuring ATSAMD51](https://www.adafruit.com/product/3857)
It's what you've been waiting for, the Feather M4 Express featuring ATSAMD51. This Feather is fast like a swift, smart like an owl, strong like a ox-bird (it's half ox, half bird, OK?) This feather is powered by our new favorite chip, the **ATSAMD51J19** - with...
In Stock
[Buy Now](https://www.adafruit.com/product/3857)
[Related Guides to the Product](https://learn.adafruit.com/products/3857/guides)
### Adafruit Metro M4 feat. Microchip ATSAMD51
[Adafruit Metro M4 feat. Microchip ATSAMD51](https://www.adafruit.com/product/3382)
Are you ready? Really ready? Cause here comes the fastest, most powerful Metro ever. The **Adafruit Metro M4** featuring the **Microchip ATSAMD51**. This Metro is like a bullet train, with its 120MHz Cortex M4 with floating point support. Your code will zig and zag...
In Stock
[Buy Now](https://www.adafruit.com/product/3382)
[Related Guides to the Product](https://learn.adafruit.com/products/3382/guides)
## Related Guides
- [Adafruit Ethernet FeatherWing](https://learn.adafruit.com/adafruit-wiz5500-wiznet-ethernet-featherwing.md)
- [Adafruit Metro M4 Express featuring ATSAMD51](https://learn.adafruit.com/adafruit-metro-m4-express-featuring-atsamd51.md)
- [Adafruit Feather M4 Express](https://learn.adafruit.com/adafruit-feather-m4-express-atsamd51.md)
- [CircuitPython 101: Basic Builtin Data Structures](https://learn.adafruit.com/basic-datastructures-in-circuitpython.md)
- [Multi-Sensor IoT Environmental Sensor Box With CircuitPython](https://learn.adafruit.com/remote-iot-environmental-sensor.md)
- [Digital Circuits 6: An EPROM Emulator](https://learn.adafruit.com/digital-circuits-6-eprom-emulator.md)
- [Program CircuitPython USB Devices with iPhone & iPad](https://learn.adafruit.com/use-circuitpython-devices-with-iphone-ipad.md)
- [Controlling Objects in Unity with a 9 DoF Sensor and Arduino](https://learn.adafruit.com/controlling-objects-in-unity-with-arduino.md)
- [Lego Neon NeoPixel Sign with CircuitPython](https://learn.adafruit.com/lego-neon-sign.md)
- [Make It Talk](https://learn.adafruit.com/make-it-talk.md)
- [STEMMA Lego base plates](https://learn.adafruit.com/stemma-lego-base-plates.md)
- [Arcade Synth Controller](https://learn.adafruit.com/arcade-synth-controller.md)
- [CircuitPython 101: Functions](https://learn.adafruit.com/circuitpython-101-functions.md)
- [Prop-Maker Keyblade](https://learn.adafruit.com/propmaker-keyblade.md)
- [CircuitPython 101: Working with Lists, Iterators and Generators](https://learn.adafruit.com/circuitpython-101-list-and-things-iterators-generators.md)
- [MQTT in CircuitPython](https://learn.adafruit.com/mqtt-in-circuitpython.md)
- [How to train new TensorFlow Lite micro speech models](https://learn.adafruit.com/how-to-train-new-tensorflow-lite-micro-speech-models.md)
- [Custom Scrolling Quote Board Matrix Display](https://learn.adafruit.com/aio-quote-board-matrix-display.md)