• 1 - if error occured.
• 0 - if there was no error.

This is MAC module routine. It initializes Ethernet controller. This function is internaly splited into 2 parts to help linker when coming short of memory.

Ethernet controller settings (parameters not mentioned here are set to default):

• RAM buffer read/write pointers in auto-increment mode.
• receive filters set to default: CRC + MAC Unicast + MAC Broadcast in OR mode.
• flow control with TX and RX pause frames in full duplex mode.
• maximum packet size is set to 1536.
• Back-to-Back Inter-Packet Gap: 0x15 in full duplex mode; 0x12 in half duplex mode.
• Non-Back-to-Back Inter-Packet Gap: 0x0012 in full duplex mode; 0x0C12 in half duplex mode.
• half duplex loopback disabled.
• LED configuration: default (LEDA-link status, LEDB-link activity).

Parameters:

• mac: RAM buffer containing valid MAC address.
• ip: RAM buffer containing valid IP address.
• configuration: ethernet duplex mode switch. Valid values:
  • _ETHERNET_CFG_HALFDUPLEX
  • _ETHERNET_CFG_FULLDUPLEX
  • _ETHERNET_CFG_SPD10
  • _ETHERNET_CFG_SPD100
  • _ETHERNET_CFG_AUTO_NEGOTIATION
  • _ETHERNET_CFG_MANUAL_NEGOTIATION

  Note : If a DHCP server is to be used, IP address should be set to 0.0.0.0.

dim 
  myMacAddr as byte[6] ' my MAC address	
  myIpAddr  as byte[4] ' my IP addr
  ...
  myMacAddr[0] = 0x00
  myMacAddr[1] = 0x14
  myMacAddr[2] = 0xA5
  myMacAddr[3] = 0x76
  myMacAddr[4] = 0x19
  myMacAddr[5] = 0x3F

  myIpAddr[0]  = 192
  myIpAddr[1]  = 168
  myIpAddr[2]  = 20
  myIpAddr[3]  = 60
  
  Ethernet_Intern_Init(myMacAddr, myIpAddr, _ETHERNET_CFG_AUTO_NEGOTIATION) 

Nothing.

This is MAC module routine. This routine enables appropriate network traffic on the MCU's internal Ethernet module by the means of it's receive filters (unicast, multicast, broadcast, crc). Specific type of network traffic will be enabled if a corresponding bit of this routine's input parameter is set. Therefore, more than one type of network traffic can be enabled at the same time. For this purpose, predefined library constants (see the table below) can be ORed to form appropriate input value.

Parameters:

• filterType: network traffic/receive filter flags. Each bit corresponds to the appropriate network traffic/receive filter:

Bit	Mask	Description	Predefined library const
0	0x01	MAC Multicast traffic/receive filter flag. When set, MAC multicast traffic will be enabled.	_ETHERNET_FILTER_TYPE_MULTICAST
1	0x02	CRC check flag. When set, packets with invalid CRC field will be discarded.	_ETHERNET_FILTER_TYPE_CRC

  Note :
• Advanced filtering available in the MCU's internal Ethernet module such as Pattern Match, Magic Packet and Hash Table can not be enabled by this routine.
  Additionaly, all filters, except CRC, enabled with this routine will work in OR mode, which means that packet will be received if any of the enabled filters accepts it.
• This routine will change receive filter configuration on-the-fly. It will not, in any way, mess with enabling/disabling receive/transmit logic or any other part of the MCU's internal Ethernet module.
  The MCU's internal Ethernet module should be properly cofigured by the means of Ethernet_Intern_Init routine.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

Ethernet_Intern_Enable(_ETHERNET_FILTER_TYPE_CRC or _ETHERNET_FILTER_TYPE_MULTICAST) ' enable CRC checking and Multicast traffic

Nothing.

This is MAC module routine. This routine disables appropriate network traffic on the MCU's internal Ethernet module by the means of it's receive filters (unicast, multicast, broadcast, crc). Specific type of network traffic will be disabled if a corresponding bit of this routine's input parameter is set. Therefore, more than one type of network traffic can be disabled at the same time. For this purpose, predefined library constants (see the table below) can be ORed to form appropriate input value.

Parameters:

• filterType: network traffic/receive filter flags. Each bit corresponds to the appropriate network traffic/receive filter:

Bit	Mask	Description	Predefined library const
0	0x01	MAC Multicast traffic/receive filter flag. When set, MAC multicast traffic will be enabled.	_ETHERNET_FILTER_TYPE_MULTICAST
1	0x02	CRC check flag. When set, packets with invalid CRC field will be discarded.	_ETHERNET_FILTER_TYPE_CRC

  Note :
• Advance filtering available in the MCU's internal Ethernet module such as Pattern Match, Magic Packet and Hash Table can not be disabled by this routine.
• This routine will change receive filter configuration on-the-fly. It will not, in any way, mess with enabling/disabling receive/transmit logic or any other part of the MCU's internal Ethernet module.
• The MCU's internal Ethernet module should be properly cofigured by the means of Ethernet_Intern_Init routine.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

Ethernet_Intern_Disable(_ETHERNET_FILTER_TYPE_CRC or _ETHERNET_FILTER_TYPE_MULTICAST) ' disable CRC checking and Multicast traffic

• 0 - upon successful packet processing (zero packets received or received packet processed successfully).
• 1 - upon reception error or receive buffer corruption. Ethernet controller needs to be restarted.
• 2 - received packet was not sent to us (not our IP, nor IP broadcast address).
• 3 - received IP packet was not IPv4.
• 4 - received packet was of type unknown to the library.

This is MAC module routine. It processes next received packet if such exists. Packets are processed in the following manner:

• ARP & ICMP requests are replied automatically.
• upon TCP request the Ethernet_Intern_UserTCP function is called for further processing.
• upon UDP request the Ethernet_Intern_UserUDP function is called for further processing.

  Note : Ethernet_Intern_doPacket must be called as often as possible in user's code.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

while true
  ...
  Ethernet_Intern_doPacket()  ' process received packets
  ...
wend

Nothing.

It writes one byte in the TCP payload.

Parameters:

• dat: data to store.
• offset: offset from the beginning of the TCP payload. Considering that the size of the Ethernet buffer is 1480 bytes including the TCP header (which occupies 20 bytes without the option fields),
  the maximal value for the offset parameter is 1460.

This routine is called either from the Ethernet_Intern_UserTCP or Ethernet_Intern_UserUDP.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim data_ as byte
...
Ethernet_Intern_writePayloadByte(data_, 0)  ' put a byte at the beginning of the TCP payload

Nothing.

It writes a requested number of bytes into TCP payload.

Parameters:

• dat: RAM buffer containing bytes to be written into the TCP payload.
• offset: offset from the beginning of the TCP payload. Considering that the size of the Ethernet buffer is 1480 bytes including the TCP header (which occupies 20 bytes without the option fields),
  the maximal value for the offset parameter is 1460.
• n: number of bytes to be written.

This routine is called either from the Ethernet_Intern_UserTCP or Ethernet_Intern_UserUDP.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim buffer as byte[17]	 

buffer = "mikroElektronika" 	 
...
Ethernet_Intern_writePayloadBytes(buffer, 0, 16)  ' put an RAM array into TCP payload

Nothing.

It writes a requested number of bytes from prgram memory into TCP payload.

Parameters:

• dat: program memory buffer containing bytes to be written into the TCP payload.
• offset: offset from the beginning of the TCP payload. Considering that the size of the Ethernet buffer is 1480 bytes including the TCP header (which occupies 20 bytes without the option fields),
  the maximal value for the offset parameter is 1460.
• n: number of bytes to be written.

This routine is called either from the Ethernet_Intern_UserTCP or Ethernet_Intern_UserUDP.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

Ethernet_Intern_writeConstPayloadBytes(@buffer, 0, 16) ' put a const bytes into TCP payload

Number of bytes written into the TCP payload.

This is MAC module routine. It stores whole string (excluding null termination) into RAM at current write location.

Parameters:

• dat: RAM buffer containing string to be written into the TCP payload.
• offset: offset from the beginning of the TCP payload. Considering that the size of the Ethernet buffer is 1480 bytes including the TCP header (which occupies 20 bytes without the option fields),
  the maximal value for the offset parameter is 1460.

This routine is called either from the Ethernet_Intern_UserTCP or Ethernet_Intern_UserUDP.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim buffer as string[16] 	 
...
buffer = "mikroElektronika"
Ethernet_Intern_writePayloadBytes(@buffer, 0) ' put an RAM array into TCP payload

Number of bytes written into the TCP payload.

This is MAC module routine. It stores whole const string (excluding null termination) into RAM at current write location.

Parameters:

• dat: RAM buffer containing const string to be written into the TCP payload.
• offset: offset from the beginning of the TCP payload. Considering that the size of the Ethernet buffer is 1480 bytes including the TCP header (which occupies 20 bytes without the option fields),
  the maximal value for the offset parameter is 1460.

This routine is called either from the Ethernet_Intern_UserTCP or Ethernet_Intern_UserUDP.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

Ethernet_Intern_writeConstPayloadString(@buffer, 0); // put a const string into TCP payload

Byte read from TCP payload.

It fetches a byte from the TCP payload, from the position detemined by the offset parameter.

Parameters:

• offset: offset from the beginning of the TCP payload. Considering that the size of the Ethernet buffer is 1480 bytes including the TCP header (which occupies 20 bytes without the option fields),
  the maximal value for the offset parameter is 1460.

This routine is called either from the Ethernet_Intern_UserTCP or Ethernet_Intern_UserUDP.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim buffer as byte  
...
buffer = Ethernet_Intern_readPayloadByte(0)  ' read a byte from TCP payload

Nothing.

It fetches requested number of bytes from the TCP payload.

Parameters:

• dat: buffer for storing bytes read from the TCP payload.
• offset: offset from the beginning of the TCP payload. Considering that the size of the Ethernet buffer is 1480 bytes including the TCP header (which occupies 20 bytes without the option fields),
  the maximal value for the offset parameter is 1460.
• numOfBytes: number of bytes to be read.

This routine is called either from the Ethernet_Intern_UserTCP or Ethernet_Intern_UserUDP.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim buffer as byte[16]
...
Ethernet_Intern_getBytes(@buffer, 0, 16) ' read an array from TCP payload

• 0 - there should not be a reply to the request.
• Length of TCP/HTTP reply data field - otherwise.

This is TCP module routine. It is internally called by the library. The user accesses to the TCP/HTTP request by using some of the Ethernet_Intern_get routines. The user puts data in the transmit buffer by using some of the Ethernet_Intern_put routines. The function must return the length in bytes of the TCP/HTTP reply, or 0 if there is nothing to transmit. If there is no need to reply to the TCP/HTTP requests, just define this function with return(0) as a single statement.

Parameters:

• remoteHost: client's IP address.
• remotePort: client's TCP port.
• localPort: port to which the request is sent.
• reqLength: TCP/HTTP request data field length.
• flags: structure consisted of two fields :
  Copy Code To Clipboard

  structure TEthInternPktFlags
    dim canCloseTCP as boolean  ' flag which closes socket
    dim isBroadcast as boolean  ' flag which denotes that the IP package has been received via subnet broadcast address
  end structure
  

  Note : The function source code is provided with appropriate example projects. The code should be adjusted by the user to achieve desired reply.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

This function is internally called by the library and should not be called by the user's code.

• 0 - there should not be a reply to the request.
• Length of UDP reply data field - otherwise.

This is UDP module routine. It is internally called by the library. The user accesses to the UDP request by using some of the Ethernet_Intern_get routines. The user puts data in the transmit buffer by using some of the Ethernet_Intern_put routines. The function must return the length in bytes of the UDP reply, or 0 if nothing to transmit. If you don't need to reply to the UDP requests, just define this function with a return(0) as single statement.

Parameters:

• remoteHost: client's IP address.
• remotePort: client's port.
• destPort: port to which the request is sent.
• flags: structure consisted of two fields :
  Copy Code To Clipboard

  structure TEthInternPktFlags
    dim canCloseTCP as boolean  ' flag which closes socket (not relevant to UDP)
    dim isBroadcast as boolean  ' flag which denotes that the IP package has been received via subnet broadcast address
  end structure
  

    Note : The function source code is provided with appropriate example projects. The code should be adjusted by the user to achieve desired reply.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

This function is internally called by the library and should not be called by the user's code.

Pointer to the global variable holding IP address.

This routine should be used when DHCP server is present on the network to fetch assigned IP address.

  Note : User should always copy the IP address from the RAM location returned by this routine into it's own IP address buffer. These locations should not be altered by the user in any case!

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim 
  ipAddr as byte[4]  ' user IP address buffer
  ...	
  memcpy(ipAddr, Ethernet_Intern_getIpAddress(), 4)  ' fetch IP address

This routine should be used when DHCP server is present on the network to fetch assigned gateway IP address.

  Note : User should always copy the IP address from the RAM location returned by this routine into it's own gateway IP address buffer. These locations should not be altered by the user in any case!

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim 
  gwIpAddr as byte[4]  ' user gateway IP address buffer
  ...	
  memcpy(gwIpAddr, Ethernet_Intern_getGwIpAddress(), 4)  ' fetch gateway IP address 

This routine should be used when DHCP server is present on the network to fetch assigned DNS IP address.

  Note : User should always copy the IP address from the RAM location returned by this routine into it's own DNS IP address buffer. These locations should not be altered by the user in any case!

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim 
  dnsIpAddr as byte[4]  ' user DNS IP address buffer
  ...	
  memcpy(dnsIpAddr, Ethernet_Intern_getDnsIpAddress(), 4)  ' fetch DNS server address 

This routine should be used when DHCP server is present on the network to fetch assigned IP subnet mask.

  Note : User should always copy the IP address from the RAM location returned by this routine into it's own IP subnet mask buffer. These locations should not be altered by the user in any case!

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim 
  IpMask as byte[4]  ' user IP subnet mask buffer
  ...	
  memcpy(IpMask, Ethernet_Intern_getIpMask(), 4)  ' fetch IP subnet mask

Configures network parameters (IP subnet mask, gateway IP address, DNS IP address) when DHCP is not used.

Parameters:

• ipMask: IP subnet mask.
• gwIpAddr gateway IP address.
• dnsIpAddr: DNS IP address.

  Note : The above mentioned network parameters should be set by this routine only if DHCP module is not used. Otherwise DHCP will override these settings.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim 
  ipMask    as byte[4]  ' network mask (for example : 255.255.255.0)
  gwIpAddr  as byte[4]  ' gateway (router) IP address
  dnsIpAddr as byte[4]  ' DNS server IP address
  ...	
  gwIpAddr[0]  = 192
  gwIpAddr[1]  = 168
  gwIpAddr[2]  = 20
  gwIpAddr[3]  = 6

  dnsIpAddr[0] = 192
  dnsIpAddr[1] = 168
  dnsIpAddr[2] = 20
  dnsIpAddr[3] = 100

  ipMask[0]    = 255
  ipMask[1]    = 255
  ipMask[2]    = 255
  ipMask[3]    = 0
  ...
  Ethernet_Intern_confNetwork(ipMask, gwIpAddr, dnsIpAddr) ' set network configuration parameters

If successful, returns MAC address, NULL otherwise.

This is ARP module routine. It sends an ARP request for given IP address and waits for ARP reply. If the requested IP address was resolved, an ARP cash entry is used for storing the configuration. ARP cash can store up to 3 entries. For ARP cash structure refer to "__Ethernet_Intern_Private.mbas" file in the compiler's Uses folder.

Parameters:

• ip: IP address to be resolved.
• tmax: time in seconds to wait for an reply.

  Note : The Ethernet services are not stopped while this routine waits for ARP reply. The incoming packets will be processed normaly during this time.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim 
  IpAddr as byte[4]  ' IP address
  ...	
  IpAddr[0] = 192 
  IpAddr[0] = 168 
  IpAddr[0] = 1 
  IpAddr[0] = 1 
  ...
  Ethernet_Intern_arpResolve(IpAddr, 5) ' get MAC address behind the above IP address, wait 5 secs for the response

• 1 - UDP packet was sent successfully.
• 0 - otherwise.

This is UDP module routine. It sends an UDP packet on the network.

Parameters:

• destIP: remote host IP address.
• sourcePort: local UDP source port number.
• destPort: destination UDP port number.
• pkt: packet to transmit.
• pktLen: length in bytes of packet to transmit.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim 
  IpAddr as byte[4]  ' remote IP address
  ...	
  IpAddr[0] = 192 
  IpAddr[0] = 168 
  IpAddr[0] = 1 
  IpAddr[0] = 1 
  ...
  Ethernet_Intern_sendUDP(IpAddr, 10001, 10001, "Hello", 5) ' send Hello message to the above IP address, from UDP port 10001 to UDP port 10001 

• pointer to the location holding the IP address - the requested host name was resolved.
• 0 - otherwise.

This is DNS module routine. It sends an DNS request for given host name and waits for DNS reply. If the requested host name was resolved, it's IP address is stored in library global variable and a pointer containing this address is returned by the routine. UDP port 53 is used as DNS port.

Parameters:

• host: host name to be resolved.
• tmax: time in seconds to wait for an reply.

The above mentioned network parameters should be set by this routine only if DHCP module is not used. Otherwise DHCP will override these settings.

  Note :

• The Ethernet services are not stopped while this routine waits for DNS reply. The incoming packets will be processed normaly during this time.
• User should always copy the IP address from the RAM location returned by this routine into it's own resolved host IP address buffer. These locations should not be altered by the user in any case!

Ethernet module has to be initialized. See Ethernet_Intern_Init.

dim 
  remoteHostIpAddr as byte[4]	' user host IP address buffer
  ...
  ' SNTP server:
  ' Zurich, Switzerland: Integrated Systems Lab, Swiss Fed. Inst. of Technology
  ' 129.132.2.21: swisstime.ethz.ch
  ' Service Area: Switzerland and Europe	
  memcpy(remoteHostIpAddr, Ethernet_Intern_dnsResolve("swisstime.ethz.ch", 5), 4) 

• 1 - network parameters were obtained successfully.
• 0 - otherwise.

This is DHCP module routine. It sends an DHCP request for network parameters (IP, gateway, DNS addresses and IP subnet mask) and waits for DHCP reply. If the requested parameters were obtained successfully, their values are stored into the library global variables.

These parameters can be fetched by using appropriate library IP get routines:

• Ethernet_Intern_getIpAddress - fetch IP address.
• Ethernet_Intern_getGwIpAddress - fetch gateway IP address.
• Ethernet_Intern_getDnsIpAddress - fetch DNS IP address.
• Ethernet_Intern_getIpMask - fetch IP subnet mask.

UDP port 68 is used as DHCP client port and UDP port 67 is used as DHCP server port.

Parameters:

• tmax: time in seconds to wait for an reply.

  Note :

• The Ethernet services are not stopped while this routine waits for DNS reply. The incoming packets will be processed normaly during this time.
• When DHCP module is used, global library variable Ethernet_Intern_userTimerSec is used to keep track of time. It is user responsibility to increment this variable each second in it's code.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

  ...	
  Ethernet_Intern_initDHCP(5) ' get network configuration from DHCP server, wait 5 sec for the response 
  ...

• 0 - lease time has not expired yet.
• 1 - lease time has expired, it's time to renew it.

This is DHCP module routine. It takes care of IP address lease time by decrementing the global lease time library counter. When this time expires, it's time to contact DHCP server and renew the lease.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

while true
  ...
  if(Ethernet_Intern_doDHCPLeaseTime() <> 0) then
    ... ' it's time to renew the IP address lease                  
  end if  
wend 

• 1 - upon success (lease time was renewed).
• 0 - otherwise (renewal request timed out).

This is DHCP module routine. It sends IP address lease time renewal request to DHCP server.

Parameters:

• tmax: time in seconds to wait for an reply.

Ethernet module has to be initialized. See Ethernet_Intern_Init.

while true 
  ...
  if(Ethernet_Intern_doDHCPLeaseTime() <> 0) then
    Ethernet_Intern_renewDHCP(5)  ' it's time to renew the IP address lease, with 5 secs for a reply                  
  end if 
  ...  
wend   

• 1 - upon success (lease time was renewed).
• 0 - otherwise (renewal request timed out).

This routine sets user selectable pins as LED indicators of network activity.

Parameters:

• ledCfg1: time in seconds to wait for an reply.
• ledCfg2: time in seconds to wait for an reply.

Ethernet module has to be initialized. See Ethernet_Intern_Init.