W5500

This library allows you to communicate with a TCP/IP network (separate from an imp’s connection to the network) using the Wiznet W5500 chip. The W5500 chip is a hardwired TCP/IP embedded Ethernet controller. The W5500 is used by the impAccelerator™ Fieldbus Gateway.

This library supports SPI integration with the W5500.

You can view the library’s source code on GitHub. Click here to see information on other versions of this library.

To include this library in your project, add #require "W5500.device.lib.nut:2.2.0" at the top of your device code

W5500 Class Usage

Constructor: W5500(interruptPin, spi[, csPin][, resetPin][, autoRetry][, setMac])

The constructor configures, resets then initializes the Wiznet chip. The reset process is blocking and can take a number of seconds. The initialization process then runs asynchronously, so be sure to register an onReady callback before opening a connection or listener.

Parameter	Data Type	Required?	Description
interruptPin	imp pin object	Yes	The pin represents a physical pin on the imp and is used for receiving interrupts from the W5500 chip. The pin can be any digital input that supports a callback on pin state change
spi	imp spi object	Yes	A configured SPI object
csPin	imp pin object	No	The pin represents a physical pin on the imp and is used to select the SPI bus. On the imp005 if you do not pass a pin into csPin you must configure the SPI with the USE_CS_L constant, Default: null
resetPin	imp pin object	No	The pin represents a physical pin on the imp and is used for sending a hard reset signal to the W5500 chip
autoRetry	Boolean	No	Whether the library should automatically retry to open a connection should one fail. Default: false. Note Not yet implemented
setMac	Boolean	No	Whether the library should set the MAC address of the chip to the imp’s own MAC (with the locally administered bit flipped). This should be set to false when using a Wiznet Wiz550io board, since it has its own MAC address. Default: true

Examples

// Setup for an imp005 Fieldbus Gateway
interruptPin <- hardware.pinXC;
resetPin     <- hardware.pinXA;

// Initialize SPI 
spiSpeed     <- 1000;
spi          <- hardware.spi0;
spi.configure(CLOCK_IDLE_LOW | MSB_FIRST | USE_CS_L, spiSpeed);

// Initialize Wiznet
wiz <- W5500(interruptPin, spi, null, resetPin);

// Setup for an impC001 

// Configure pins 
cs           <- hardware.pinS;
resetPin     <- hardware.pinYC;
// Note: This is not the default interrupt pin for the mikroBus.
// The default pin YD doesn't allow for a state change callback.
// Apply solder bridge to W4 on back of breakout board to connect
// interrupt to pin YL.
interruptPin <- hardware.pinYL;

// Initialize SPI 
speed        <- 1000;
spi          <- hardware.spiPQRS;
spi.configure(CLOCK_IDLE_LOW | MSB_FIRST, speed);

// Initialize Wiznet
wiz <- W5500(interruptPin, spi, cs, resetPin);

// Setup for an imp001 

// Configure pins 
cs           <- hardware.pin8;
resetPin     <- hardware.pin9;
interruptPin <- hardware.pin1;

// Initialize SPI 
speed        <- 1000;
spi          <- hardware.spi257
spi.configure(CLOCK_IDLE_LOW | MSB_FIRST, speed);

// Initialize Wiznet
wiz <- W5500(interruptPin, spi, cs, resetPin);

W5500 Class Methods

configureNetworkSettings(sourceIP[, subnetMask][, gatewayIP][, mac])

This method takes the network information and sets the data into the relevant registers in the Wiznet chip.

Parameters

Parameter	Data Type	Required?	Description
sourceIP	String or an array of integers	Yes	The IP address for Wiznet adapter. For example, the address 192.168.1.37 can be passed in as an array, [192, 168, 1, 37], or as a string "192.168.1.37"
subnetMask	String or an array of four integers	No	The subnet mask. For example, a subnet mask of 255.255.255.0 can be passed in as an array, [255, 255, 255, 0], or as a string "255.255.255.0". Default: null
gatewayIP	String or an array of four integers	No	The IP address of the gateway or router. For example, the address 192.168.1.1 can be passed in as an array, [192, 168, 1, 1], or as a string "192.168.1.1". Default: null
mac	String or an array of six integers	No	The MAC address to assign to the Wiznet adapter. It is easiest to let the MAC address be set automatically by leaving this as null. You can manually enter the address 0c:2a:69:09:76:64 by passing it into an array, [0x0c, 0x2a, 0x69, 0x09, 0x76, 0x64], or as a string "0c2a69097664". Default: null

Returns

The instance (this).

Examples

// Configured using strings
wiz.configureNetworkSettings("192.168.1.37", "255.255.255.0", "192.168.1.1");

// Configured using arrays
wiz.configureNetworkSettings([192,168,1,37], [255,255,255,0], [192,168,1,1]);

onReady(callback)

This method registers a callback function that will be triggered when the W5500 initialization is completed and the W5500 is ready for use.

Parameters

Parameter	Data Type	Required?	Description
callback	Function	Yes	A function that will be executed when the initialization of the W5500 has completed successfully. It will be called immediately if the initialization has already been completed. It has no parameters of its own

Returns

The instance (this).

Example

// The callback function will not run until the 5500 has finished initializing
wiz.onReady(function() {
    server.log("The Wiznet W5500 is ready");
}.bindenv(this));

openConnection(ip, port[, mode][, callback])

This method finds a socket that is not in use and initializes a connection for the socket. Initialization must be complete before this method is called or an error will be thrown.

Parameters

Parameter	Data Type	Required?	Description
ip	String or an array of four integers	Yes	The destination IP address. For example, the address 192.168.1.37 can be passed in as an array, [192, 168, 1, 37], or as a string "192.168.1.37"
port	An integer or an array of two integers	Yes	The destination port. For port 4242, pass in an array, [0x10, 0x92], or an integer 4242
mode	Constant	No	The mode of communication to be used by the socket. The list of available options is listed in the table below. Currently only TCP is supported. Default: W5500_SOCKET_MODE_TCP
callback	Function	No	A callback function that is passed an error message or the opened connection. The callback’s parameters are listed below. Default: null

Communication Mode Constants

Communication Mode	Value
W5500_SOCKET_MODE_TCP	0x01
W5500_SOCKET_MODE_UDP	0x02

On Open Callback Parameters

Parameter	Data Type	Description
error	String	An error message if there was a problem, or null if successful
connection	A W5500.Connection object	An instantiated object representing the open socket connection

Returns

Nothing.

Examples

// Using a string and a integer
local destIp = "192.168.1.42";
local destPort = 4242;
wiz.openConnection(destIp, destPort, function(error, connection) {
    if (error) {
        server.error(error);
    } else {
        // Work with connection
    }
}.bindenv(this));

// Using arrays
local destIp = [192, 168, 1, 42];
local destPort = [0x10, 0x92];
wiz.openConnection(destIp, destPort, function(error, connection) {
    if (error) {
        server.error(error);
    } else {
        // Work with connection
    }
}.bindenv(this));

listen(port, callback)

This method finds a socket that is not in use and sets up a TCP server. Initialization must be complete before this method is called or an error will be thrown.

Parameters

Parameter	Data Type	Required?	Description
port	An integer	Yes	The port to listen on for connections
callback	Function	Yes	A callback function that is passed an error message, or the established remote connection is established. The table below lists its parameters

 

Callback Parameter	Data Type	Description
error	String	An error message if there was a problem, or null if successful
connection	A W5500.Connection object	An instantiated object representing the open socket connection

Returns

Nothing.

Example

local port = 80;
wiz.listen(port, function(error, connection) {
    if (error) {
        server.error(error);
    } else {
        local ip = connection.getIP();
        local port = connection.getPort();
        server.log(format("Connection established from %d.%d.%d.%d:%d", ip[0], ip[1], ip[2], ip[3], port));
    }
}.bindenv(this))

reset([softReset])

This method causes the Wiznet chip to undergo a reset and re-initialization. The reset is a blocking operation that will take 1+ seconds to close each socket that is in use, as well as 1+ second for the actual chip reset. When the reset operation is complete an asynchronous initialization is performed. When initialization is complete the callback registered with onReady() is triggered. It is recommended that you use the onReady callback to reconfigure and continue Wiznet operation. The data sheet for the Wiznet chip recommends a hardware reset (the default behavior), however no reset pin is configured the optional parameter can be used to perform a software reset.

Parameters

Parameter	Data Type	Required?	Description
softReset	Boolean	No	Pass true to trigger a soft reset, or false for a hard reset. Default: false

Returns

Nothing.

Examples

// Perform a hardware reset
wiz.onReady(function() {
    // Reset complete, so configure the Wiznet 5500 here
}.bindenv(this));
wiz.reset();

// A software reset
wiz.onReady(function() {
    // Reset complete, so configure the Wiznet 5500 here
}.bindenv(this));
wiz.reset(true);

setNumberOfAvailableSockets(numSockets)

This method configures the Wiznet 5500’s buffer memory allocation by dividing the available memory between the number of required sockets evenly. If you need a greater buffer per socket, allocate fewer sockets. The default behavior is to allocate eight sockets.

Parameters

Parameter	Data Type	Required?	Description
numSockets	Integer	Yes	The number of sockets required

Returns

Integer — The number of actual sockets set.

Example

wiz.setNumberOfAvailableSockets(2);

isPhysicallyConnected()

This method indicates whether an Ethernet cable is plugged into the socket to which the W5500 is connected.

Returns

Boolean — true if the W5500 is physically connected, otherwise false.

Example

server.log(format("Cable %s connected.", wiz.isPhysicallyConnected() ? "is" : "is not"));

forceCloseAllSockets()

This method closes all sockets by sending a disconnect request followed by a close request.

Returns

Nothing.

Example

wiz.forceCloseAllSockets();

getNumSocketsFree()

This method determines the number of sockets that are still available for use.

Returns

Integer — The number of sockets available.

Example

if (wiz.getNumSocketsFree() == 0) server.error("Wiznet is busy.");

W5500.Connection Class Usage

This connection class is used to perform all actions using the connection. This includes initializing and ending a connection to a socket, as well as using the connection for the transmission and reception of data packets.

You do not instantiate W5500.Connection objects yourself. Instead, they will be generated for you by the methods detailed above.

W5500.Connection Class Methods

open([callback])

This method opens a socket then sets up the connection. It is called as part of openConnection() and should not be called directly.

Parameters

Parameter	Data Type	Required?	Description
callback	Function	No	A function to be called when the connection is open, or an error occurred

Returns

The instance (this).

close([callback])

This method closes a connection via the W5500.

Parameters

Parameter	Data Type	Required?	Description
callback	Function	No	A function to be called when the connection is closed, or an error occurred. It has no parameters of its own

Returns

Nothing.

Example

connection.close(function() {
    server.log("Connection closed");
}.bindenv(this));

getSocket()

This method retrieves the ID of the socket.

Returns

Integer — The socket ID.

Example

server.log("This connection is using socket " + connection.getSocket());

isEstablished()

This method indicates whether a connection is open via the W5500.

Returns

Boolean — true if a connection is established, otherwise false.

Example

server.log("A W5500 link is " + (connection.isEstablished() ? "established" : "not established"));

onReceive([callback])

This method registers a callback function that will be triggered when data is received.

Parameters

Parameter	Data Type	Required?	Description
callback	Function	No	A function to be called when data is received. Its parameters are listed below

 

Parameter	Data Type	Description
error	String	An error message if there was a problem, or null if it was successful
data	Blob	The data that was received

Returns

The instance (this).

Example

connection.onReceive(function(error, data) {
    if (error) {
        server.error(error);
    } else {
        server.log("Received data: " + data);
    }
}.bindenv(this));

onDisconnect([callback])

This method registers a callback function that will be triggered when the connection is broken.

Parameters

Parameter	Data Type	Required?	Description
callback	Function	No	A function to be called when the W5500 is disconnects. Its parameters are listed below

 

Callback Parameter	Data Type	Description
error	String	An error message if there was a problem, or null if it was successful

Returns

The instance (this).

Example

connection.onDisconnect(function(error) {
    if (error) server.error(error);
    server.log("Disconnected");
}.bindenv(this));

onClose([callback])

This method registers a callback function that will be triggered when the connection is fully closed and removed from the system.

Parameters

Parameter	Data Type	Required?	Description
callback	Function	No	A function to be called when the connection is closed. It has no parameters of its own

Returns

The instance (this).

Example

connection.onClose(function() {
    server.log("Connection closed");
}.bindenv(this));

transmit(data[, callback])

This method is called within a connection to transmit the data through the socket.

Parameters

Parameter	Data Type	Required?	Description
data	Blob or string	Yes	The data to be transmitted
callback	Function	No	The callback triggered when data was sent successfully or a timeout occurred. Its parameters are listed below

 

Callback Parameter	Data Type	Description
error	String	An error message if there was a problem, or null if it was successful

Returns

The instance (this).

Example

local data = "Hello, world.";
connection.transmit(data, function(error) {
    if (error) {
        server.error(error);
    } else {
        server.log("Data sent successfully");
    }
}.bindenv(this));

receive([callback])

This method is an alternative to onReceive() and which will temporarily override onReceive(). It receives the next available data packet on the connection.

Parameters

Parameter	Data Type	Required?	Description
callback	Function	No	The callback triggered when data was received. Its parameters are listed below

 

Callback Parameters	Data Type	Description
error	String	An error message if there was a problem, or null if it was successful
data	Blob	The data that was received

Returns

The instance (this).

Example

connection.receive(function(error, data) {
    if (error) {
        server.error(error);
    } else {
        server.log("Received data: " + data);
    }
}.bindenv(this));

W5500.Driver Class

The W5500.Driver class is responsible for a number of low-levels operations, including opening and closing sockets, setting and getting memory, and setting and getting socket modes. The W5500 and W5500.Connection classes make use of this class.

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version	Source Code	Notes
1.0.0	GitHub	Initial release
2.0.0	GitHub	Major bug fixes; update library name to new naming convention
2.1.0	GitHub	Add setMac parameter to WS5500 constructor; bug fixes
2.1.0	GitHub	Fixed a typo causing a runtime issue
2.2.0	GitHub	Updated MAC address handling to support cellular imps

License

This library is available under the MIT License.