EtherSia
A minimal IPv6 Ethernet library for Arduino.
Public Member Functions | List of all members
EtherSia Class Referenceabstract

Main class for sending and receiving IPv6 messages using the ENC28J60 Ethernet controller. More...

#include <EtherSia.h>

Public Member Functions

 EtherSia ()
 Default Constructor.
 
boolean begin ()
 Configure the Ethernet interface and get things ready. More...
 
void disableAutoconfiguration ()
 Disable stateless auto-configuration (SLAAC) More...
 
void enableAutoconfiguration ()
 Enable stateless auto-configuration (SLAAC) More...
 
void setGlobalAddress (IPv6Address &address)
 Manually set the global IPv6 address for the Ethernet Interface from an IPv6Address object. More...
 
void setGlobalAddress (const char *address)
 Manually set the global IPv6 address for the Ethernet Interface from human readable string. More...
 
IPv6AddressglobalAddress ()
 Get the global IPv6 address of the Ethernet Interface. More...
 
IPv6AddresslinkLocalAddress ()
 Get the link-local address of the Ethernet Interface This is generated automatically from the MAC address. More...
 
MACAddresslocalMac ()
 Get the local MAC address of this network interface. More...
 
MACAddressrouterMac ()
 Get the MAC address of the router on the local subnet. More...
 
void setRouter (MACAddress &routerMac)
 Manually set the MAC address of the router on the local subnet. More...
 
boolean setRouter (const char *address)
 Manually set the IPv6 address of the router on the local subnet. More...
 
boolean setRouter (IPv6Address &address)
 Manually set the IPv6 address of the router on the local subnet. More...
 
uint8_t isOurAddress (const IPv6Address &address)
 Check to see if an IPv6 address belongs to this Ethernet interface. More...
 
uint8_t inOurSubnet (const IPv6Address &address)
 Check if an address is in the same subnet as us. More...
 
void setDnsServerAddress (IPv6Address &address)
 Set the IPv6 address DNS server to use for hostname lookups. More...
 
IPv6AddressdnsServerAddress ()
 Get the IPv6 address of the DNS server. More...
 
uint16_t receivePacket ()
 Check if there is an IPv6 packet waiting for us and copy it into the buffer. More...
 
void rejectPacket ()
 Check the received packet, and reply with a rejection packet. More...
 
boolean bufferContainsReceived ()
 Check if the packet buffer contains a valid received packet. More...
 
IPv6Packetpacket ()
 Get a reference to the packet buffer (the last packet sent or received). More...
 
void send ()
 Send the packet currently in the packet buffer.
 
void prepareSend ()
 Get the packet buffer ready to send a packet. More...
 
void prepareReply ()
 Convert the packet current in the packet buffer into a reply. More...
 
IPv6AddresslookupHostname (const char *hostname)
 Lookup a hostname using DNS and get an IPv6 address for it. More...
 
MACAddressdiscoverNeighbour (const char *address)
 Perform Neighbour Discovery for an IPv6 address on the local subnet. More...
 
MACAddressdiscoverNeighbour (IPv6Address &address, uint8_t attempts=NEIGHBOUR_SOLICITATION_ATTEMPTS)
 Perform Neighbour Discovery for an IPv6 address on the local subnet. More...
 
void tcpSendRSTReply ()
 Send a reply with a TCP RST packet.
 
virtual uint16_t sendFrame (const uint8_t *data, uint16_t datalen)=0
 Send an Ethernet frame. More...
 
virtual uint16_t readFrame (uint8_t *buffer, uint16_t bufsize)=0
 Read an Ethernet frame. More...
 

Detailed Description

Main class for sending and receiving IPv6 messages using the ENC28J60 Ethernet controller.

Create an instance of this class for talking to your Ethernet Controller

Member Function Documentation

◆ begin()

boolean EtherSia::begin ( )

Configure the Ethernet interface and get things ready.

If auto-configuration has not been disabled, then stateless auto-configuration will start - attempting to get an IP address and Router address using IGMPv6.

Returns
Returns true if setting up the Ethernet interface was successful

References IPv6Address::setEui64(), and IPv6Address::setLinkLocalPrefix().

◆ bufferContainsReceived()

boolean EtherSia::bufferContainsReceived ( )
inline

Check if the packet buffer contains a valid received packet.

Returns
  • true: the buffer contains a valid packet received over the network
  • false: the buffer contains a packet we generated, or is invalid in some way

◆ disableAutoconfiguration()

void EtherSia::disableAutoconfiguration ( )
inline

Disable stateless auto-configuration (SLAAC)

Disables sending Router Solicitations and accepting Router Advertisements.

Disable auto-configuration if you would like to use a statically configured global address, or only want to use link-local addressing.

Examples:
MinimalStatic.ino.

◆ discoverNeighbour() [1/2]

MACAddress * EtherSia::discoverNeighbour ( const char *  address)

Perform Neighbour Discovery for an IPv6 address on the local subnet.

This method takes an IPv6 address and resolves it to a MAC address.

It is recommended that this method is called within setup(), to avoid packets being lost within loop().

Note
You probably don't need to call this function directly.
Parameters
addressThe IPv6 address to perform discovery on
Returns
An pointer to a MAC address or NULL if the discovery failed

◆ discoverNeighbour() [2/2]

MACAddress * EtherSia::discoverNeighbour ( IPv6Address address,
uint8_t  attempts = NEIGHBOUR_SOLICITATION_ATTEMPTS 
)

Perform Neighbour Discovery for an IPv6 address on the local subnet.

This method takes an IPv6 address and resolves it to a MAC address.

It is recommended that this method is called within setup(), to avoid packets being lost within loop().

Note
You probably don't need to call this function directly.
Parameters
addressThe IPv6 address to perform discovery on
attemptsThe number of ICMPv6 packets to send before giving up
Returns
An pointer to a MAC address or NULL if the discovery failed

References IP6_PROTO_ICMP6, IPv6Address::isLinkLocal(), NEIGHBOUR_SOLICITATION_TIMEOUT, packet(), IPv6Packet::protocol(), and receivePacket().

◆ dnsServerAddress()

IPv6Address& EtherSia::dnsServerAddress ( )
inline

Get the IPv6 address of the DNS server.

Returns
The DNS Server address as an IPv6Address object

◆ enableAutoconfiguration()

void EtherSia::enableAutoconfiguration ( )
inline

Enable stateless auto-configuration (SLAAC)

Note
Stateless auto-configuration is enabled by default.

◆ globalAddress()

IPv6Address& EtherSia::globalAddress ( )
inline

Get the global IPv6 address of the Ethernet Interface.

If this is called after begin(), then it will return the IP address assigned during stateless auto-configuration.

Returns
The Global IP address as an IPv6Address object
Examples:
MiniHTTPServer.ino, Minimal.ino, NanodeUDPServer.ino, SNTPClient.ino, TFTPServer.ino, and WebToggler.ino.

◆ inOurSubnet()

uint8_t EtherSia::inOurSubnet ( const IPv6Address address)

Check if an address is in the same subnet as us.

Parameters
addressthe IPv6Addrss to check
Returns
the type of address IPv6AddressType or 0 if it is not in the same subnet
Note
assumes that the subnet mask is /64

References ADDRESS_TYPE_GLOBAL, ADDRESS_TYPE_LINK_LOCAL, IPv6Address::inSameSubnet(), and IPv6Address::isLinkLocal().

◆ isOurAddress()

uint8_t EtherSia::isOurAddress ( const IPv6Address address)

Check to see if an IPv6 address belongs to this Ethernet interface.

Parameters
addressthe IPv6Addrss to check
Returns
the type of address IPv6AddressType or 0 if it is not our address

References ADDRESS_TYPE_GLOBAL, ADDRESS_TYPE_LINK_LOCAL, ADDRESS_TYPE_MULTICAST, IPv6Address::isLinkLocalAllNodes(), and IPv6Address::isSolicitedNodeMulticastAddress().

◆ linkLocalAddress()

IPv6Address& EtherSia::linkLocalAddress ( )
inline

Get the link-local address of the Ethernet Interface This is generated automatically from the MAC address.

Returns
The Link-Local IP address as an IPv6Address object
Examples:
MiniHTTPServer.ino, NanodeUDPServer.ino, and TFTPServer.ino.

◆ localMac()

MACAddress& EtherSia::localMac ( )
inline

Get the local MAC address of this network interface.

Returns
The local MAC address of this network interface

◆ lookupHostname()

IPv6Address * EtherSia::lookupHostname ( const char *  hostname)

Lookup a hostname using DNS and get an IPv6 address for it.

This method receives and processes UDP packets while it is waiting for the DNS reply. Other packets may be missed / lost while this method is running.

It is recommended that this method is called within setup(), to avoid packets being lost within loop().

Note
You probably don't need to call this function directly.
Parameters
hostnameThe hostname to look up
Returns
An pointer to a IPv6 address or NULL if the lookup failed

References UDPSocket::havePacket(), nextRequest, UDPSocket::payload(), UDPSocket::payloadLength(), receivePacket(), Socket::send(), Socket::setRemoteAddress(), and udp.

◆ packet()

IPv6Packet& EtherSia::packet ( )
inline

Get a reference to the packet buffer (the last packet sent or received).

There is a single buffer that is use for both sending and receiving packets, so the packet returned may be in either state.

It is also possible that it is an invalid or uninitialised packet.

Returns
A reference to an IPv6Packet
Examples:
PacketPrinter.ino, and PingClient.ino.

◆ prepareReply()

void EtherSia::prepareReply ( )

Convert the packet current in the packet buffer into a reply.

This method sets:

  • EtherType, IP version, Traffic Class, Flow Label, Hop Limit
  • Sets the IPv6 destination and to the source address
  • Sets the IPv6 source address to either our link local or global address
  • Swaps the Ethernet source and destination addresses

References IPv6Packet::etherSource(), packet(), prepareSend(), IPv6Packet::setDestination(), IPv6Packet::setEtherDestination(), and IPv6Packet::source().

◆ prepareSend()

void EtherSia::prepareSend ( )

Get the packet buffer ready to send a packet.

This method sets:

  • EtherType, IP version, Traffic Class, Flow Label, Hop Limit
  • Ethernet and IPv6 source address
  • Ethernet Destination address

It should be called after setting the IPv6 source and destination addresses

References IPv6Packet::destination(), IPv6Packet::init(), IPv6Address::isLinkLocal(), IPv6Address::isZero(), packet(), IPv6Packet::setEtherSource(), and IPv6Packet::setSource().

◆ readFrame()

virtual uint16_t EtherSia::readFrame ( uint8_t *  buffer,
uint16_t  bufsize 
)
pure virtual

Read an Ethernet frame.

Parameters
buffera pointer to a buffer to write the packet to
bufsizethe available space in the buffer
Returns
the length of the received packet or 0 if no packet was received

Implemented in EtherSia_W5100, EtherSia_W5500, EtherSia_ENC28J60, EtherSia_Dummy, and EtherSia_LinuxSocket.

◆ receivePacket()

uint16_t EtherSia::receivePacket ( )

Check if there is an IPv6 packet waiting for us and copy it into the buffer.

If there is no packet available this method returns 0.

Returns
The length of the packet, or 0 if no packet was received
Examples:
MiniHTTPServer.ino, Minimal.ino, MinimalStatic.ino, NanodeUDPClient.ino, NanodeUDPServer.ino, PacketPrinter.ino, PingClient.ino, SNTPClient.ino, Syslog.ino, TFTPServer.ino, and WebToggler.ino.

References IP6_PROTO_ICMP6, IPv6Packet::isValid(), packet(), IPv6Packet::protocol(), and readFrame().

◆ rejectPacket()

void EtherSia::rejectPacket ( )

Check the received packet, and reply with a rejection packet.

Calling this function is optional. If you don't call it the packet will just be ignored. This is similar to the difference between drop and reject on a firewall.

  • If the packet has already been replied to, it is ignored
  • If it was sent to a multicast address, it is ignored
  • If it is a TCP packet, a TCP RST reply is sent
  • It it was sent to a UDP port, an ICMPv6 Destination Unreachable reply is sent
  • If it is an unknown protocol, an ICMPv6 Unrecognised Next Header reply is sent
Examples:
MiniHTTPServer.ino, NanodeUDPClient.ino, NanodeUDPServer.ino, PingClient.ino, SNTPClient.ino, Syslog.ino, TFTPServer.ino, and WebToggler.ino.

References IPv6Packet::destination(), IP6_PROTO_ICMP6, IP6_PROTO_TCP, IP6_PROTO_UDP, IPv6Address::isMulticast(), packet(), IPv6Packet::protocol(), and tcpSendRSTReply().

◆ routerMac()

MACAddress& EtherSia::routerMac ( )
inline

Get the MAC address of the router on the local subnet.

This is used as the Ethernet destination address for packets that need to be sent outside of the subnet.

Typically this is set during the stateless auto-configuration process when you call begin().

Returns
The MAC address of the router

◆ sendFrame()

virtual uint16_t EtherSia::sendFrame ( const uint8_t *  data,
uint16_t  datalen 
)
pure virtual

Send an Ethernet frame.

Parameters
dataa pointer to the data to send
datalenthe length of the data in the packet
Returns
the number of bytes transmitted

Implemented in EtherSia_W5100, EtherSia_W5500, EtherSia_ENC28J60, EtherSia_Dummy, and EtherSia_LinuxSocket.

◆ setDnsServerAddress()

void EtherSia::setDnsServerAddress ( IPv6Address address)
inline

Set the IPv6 address DNS server to use for hostname lookups.

Parameters
addressThe DNS Server IP address

◆ setGlobalAddress() [1/2]

void EtherSia::setGlobalAddress ( IPv6Address address)
inline

Manually set the global IPv6 address for the Ethernet Interface from an IPv6Address object.

If using a static global address, it would be a good idea to disable auto-configuration using disableAutoconfiguration() before calling begin().

Parameters
addressThe Global IP address for this Ethernet interface
Examples:
MinimalStatic.ino.

◆ setGlobalAddress() [2/2]

void EtherSia::setGlobalAddress ( const char *  address)
inline

Manually set the global IPv6 address for the Ethernet Interface from human readable string.

If using a static global address, it would be a good idea to disable auto-configuration using disableAutoconfiguration() before calling begin().

Parameters
addressThe Global IP address for this Ethernet interface

References IPv6Address::fromString().

◆ setRouter() [1/3]

void EtherSia::setRouter ( MACAddress routerMac)
inline

Manually set the MAC address of the router on the local subnet.

This is used as the Ethernet destination address for packets that need to be sent outside of the subnet.

Note
You don't normally need to use this if auto-configuration is enabled, which it is by default.
Parameters
routerMacThe MAC address of the router
Examples:
MinimalStatic.ino.

References routerMac().

◆ setRouter() [2/3]

boolean EtherSia::setRouter ( const char *  address)

Manually set the IPv6 address of the router on the local subnet.

Neighbour discovery is used to resolve this to a MAC address.

Note
You don't normally need to use this if auto-configuration is enabled, which it is by default.
Parameters
addressThe IPv6 address of the router, as C string
Returns
true if setting the router address was successful

References setRouter().

◆ setRouter() [3/3]

boolean EtherSia::setRouter ( IPv6Address address)

Manually set the IPv6 address of the router on the local subnet.

Neighbour discovery is used to resolve this to a MAC address.

Note
You don't normally need to use this if auto-configuration is enabled, which it is by default.
Parameters
addressThe IPv6 address of the router
Returns
true if setting the router address was successful

References discoverNeighbour().