Mac Home Automation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====Wiznet Serial To Ethernet Configuration=====

{{:tutorials:wiznet_single_port_hero.png?300 |}}{{:tutorials:wiznet_two_port_hero.png?300|}}



[[https://www.wiznet.io|Wiznet]] Make a series of excellent Serial to Ethernet adaptors. Any serially connected device in XTension can also be connected over the network with one of these, and many others, without having to deal with things like virtual com ports or any other software or driver installs on your Mac server. This document concerns configuring them on the Mac without having to resort to getting a Windows machine to run their configuration software.

>**NOTE: This page deals with the newer Wiznet devices that are shipping as of October 2023. These include, but are not limited to, the WIZ750SR-110 which is the single port version and the WIZ750SR-125 dual port version. If you are using the older WIZ110SR boards that have been around forever please see the [[:wiznet|Wiznet Configurator]] page for more info on setting those up. They use an entirely different system though our configurator app is available for Mac to make the setup easier for them as well.**


Wiznet has written their most recent coniguration software in Python so it should theoritically run on the Mac as is. I was unable to get the GUI version of their app to run here due to errors when trying to install the QT libraries which are needed to give a python app a regular user interface. You may have better luck and if you wish I encourage you to [[https://docs.wiznet.io/Product/S2E-Module/WIZ750SR/configuration-tool-manual-new-EN|try it]] and let me know if you can succeed where I failed.  The also support a command line version of the tool which runs just fine, but it slightly more complicated to use. I am documenting the process here to make it easier, but this tutorial does assume you have a certain amount of comfort at the command line in MacOS.

While this should work with any of the WIZ75xxx series devices, the two I have tested are pictured above and are the WIZ750SR-110 for the single port version and the WIZ752SR-125 for the dual port version. See the purchasing section at the very bottom for links to possible places to purchase from.

-----
====Make sure you have a recent version of Python3 installed====

If you already know that you do have Python3 installed you can skip this step.

MacOS no longer comes with a version of Python pre-installed, it is easy to get a recent version from the python distribution site. If you don’t know if you might have already installed it you can check that by doing the following:

Open the Terminal app and enter the command:
<code>
python3 --version
</code>

If you have a version of python3 installed already you should see a single line saying something like “Python 3.10.1” It must have the 3 at the beginning, but as long as the rest is newer than 3.7 you should be good to go.

If you get an error that the command was not found then you need to install that from the [[https://www.python.org/downloads/|Python.org Download Site]] There should be a bit yellow button at the top of the page that says something about Download For MacOS. This is a standard MacOS installer and you can run it like you would any other. Once that is completely close your terminal window and open another one just to make sure it’s got a clean environment and try the test above again. This time you’ll get the version line showing it’s working.

-----
====Download the Command Line Tools:====
Unfortunately I also could not get their command line tools as currently available on GitHub to work at all. There seem to be some basic logical flaws in the validation routines and so no parameters you enter will be accepted at all. I was able to fork their code and fix the problems. Please go to [[https://github.com/PlanetaryGear/WIZnet-S2E-Tool|My Github Archive]] and find the green button above the code labeled “Code” click that and select “Download Zip.” Unzip the file and move the directory somewhere convienient that isn’t inside your Applications folder. The location doesnt matter but you need to be able to find it again..

Once those are in place switch to the Terminal again and type “cd “ thats the letters c, d and then a space. Then drag the folder from above into the Terminal window. It will put the full path to the folder after the cd command. Press enter and now we’re ready to test them. In that terminal window you can now verify the operation of it by asking it for it’s version number:

<code>
python3 ./wizconfig.py --version
</code>

Should return something like: "WIZnet-S2E-Tool v1.3.0” though that version number may get larger over time if I need to update it. If you see that then all is working and you’re ready to start configuring your devices.

-----
====Find Your Devices:====
>**NOTE: Since by default factory settings have all Wiznet devices set to the same default IP address it probably isn’t possible to setup more than one at a time. If you connect more than 1 board at factory settings they will bump into each other and only 1 of them will actually respond.**


At this time if you haven’t already, power up the device you want to configure and connect it to an ethernet cable.

Run the search command:
<code>
python3 ./wizconfig.py --search
</code>

The output will be a count of devices found and an entry line or each one giving some important info about them. Most important to us at this stage is the MAC address which is used in all future setup steps.

<code>
[Result] 1 device(s) detected.

* Device 1: 00:08:DC:xx:xx:xx [WIZ752SR-12x] | 192.168.11.2 | OPEN | Version: 2.0.0 
</code>


That first entry of 6 hex numbers is the Mac address. **Make a note of it! There is no other really good way to identify the boards so you must have a list of them and what they connect to and what their static IP addresses are supposed to be. Do not rely on this tool to help you figure out which board is which once you have more than one of them installed.**

You can see thats a goofy IP address, most likely not even on the same subnet with the rest of your network, but this doesn’t matter as we are currently communicating by UDP broadcast which doesn’t care about such things.

If your card has already been setup and might have some changed from the default settings now is a good time to do a factory reset on it to make sure nothing hidden causes problems with it’s new job. You can do that via the command:

<code>
python3 ./wizconfig.py --device 00:08:DC:xx:xx:xx --factory
</code>

The card will reboot with the default everything and you can continue to setup safely.

-----
====Network Settings:====

First lets set up networking settings. While the device can use your DHCP server to get an address if you want XTension interfaces to be able to connect to it, then it MUST have a static IP address on your network. You have a block of these outside of the DHCP range setup on your router dont you? If not you should go do that now.

Here are the commands we’re going to send, all in one packet to the device:

  * **device** and then the MAC address we got from the search command above
  * **alloc** this gets passed either a 0 for static IP or a 1 for DHCP
  * **ip** this, surprisingly enough, is the IP address you wish the device to use after it reboots
  * **subnet** for most networks this is “255.255.255.0” but put in the same value that your mac has.
  * **gw** this is the gateway or router address. This is probably not needed since this device is never going to send packets out to or receive packets in from the internet itself, but setting it properly may keep other weird things from happening later. In my case this would be set to “192.168.0.1” set it to the same value as in your Mac’s network settings.
  * **dns** Again it’s not ever going to need to look up a domain name so this may not be needed, to avoid weird things later set it to the same address you set the gateway/router value to as these will all handle DNS lookup requests. If yours doesn’t you already know this has to be set to something different.
 
Now go startup a text editor and compose this command there for easier editing and management as it’s a long string with a lot of info. When you’re confident it’s setup you can cut and paste it into that terminal window to send the config. In this example I’m going to set it to a static IP of 192.168.0.97 please replace that, the MAC address and the other addresses with whatever makes sense in your system. And I am going to restate that you need a document on your server that both keeps track of what static IP’s you have allocated for everything as well as a list of the MAC addresses of all your Wiznet boards and what they are connected to and the basic settings they need so that you can reconfigure them or replace them without having to redo all this math. Seriously I can’t emphasize enough how important this is to your health, safety and sanity.

<code>
python3 ./wizconfig.py --device 00:08:DC:xx:xx:xx --alloc 0 --ip 192.168.0.97 --subnet 255.255.255.0 --gw 192.168.0.1 --dns 192.168.0.1
</code>

So adjust that command in your own text editor, then paste it into the terminal window and press return. You should see something like:

<code>
* Single device config: 00:08:DC:xx:xx:xx

Device[00:08:DC:xx:xx:xx] configuration complete!
    01) IM: 0                 | IP address Allocation Mode: Static IP
    02) LI: 192.168.0.97      | Local IP address: 192.168.0.97
    03) SM: 255.255.255.0     | Subnet mask: 255.255.255.0
    04) GW: 192.168.0.1       | Gateway address: 192.168.0.1
    05) DS: 192.168.0.1       | DNS Server address: 192.168.0.1
</code>

The device will reboot and come back up on the network with it’s new network settings. It will now be accessible from XTension. You can verify that everything is setup by doing another search command as above and seeing the new info in the list. At this point you could connect up another device to set it up on the network, or continue to setting up the serial port and other settings in the next step.

-----
====Serial Port and Comm Settings:====

XTension and these configuration tools support both the single port and the dual port versions of these boards. The second portion of commands below will apply only to the dual port versions. The setup of the first port is the same for both and you must include the index of 0 as shown even if your board only has a single port.

>**NOTE: XTension only supports these devices in “Server” mode. They have 3 modes, Client, Server and Mixed. If you set anything other than Server XTension will not be able to connect to them.**

We will be setting the ports to operate in Server mode, then assigning them a port number. 5000 is the default for port 1 and if you have a second port it’s default is 5001. These do not need to be changed. If you have a reason to change them just make sure you enter the same numbers in the XTension interfaces. XTension normally uses the default of 10000 as the port number as that is the default that was used by the older cards. You can change it in one place or the other they just have to be the same.

  * **nmode0** this is the networking mode for port 0. It must be set to **1** for tcp server.
  * **port0** this is the tcp port number the first serial port will be available on. Defaults to **5000**
  * **baud0** the baud rate of the serial port. This will depend on the device that you’re connecting and you’ll need to see that documentation or the documentation of the plugin in XTension for the information on this.
  * **ka** set to 1 to enable TCP keep alive packets. This helps with long term connections that might not have a lot of traffic.

In addition to those there may be other serial port settings that you have to change. For every device I can think of these are fine left as the default but should you need to change them for the first serial port they are:

  * **data0** 0 for 7-bit 1 for 8-bit
  * **parity0** 0 for none, 1 for odd, 2 for even
  * **stop0** 0 for 1 stop bit, 1 for 2 stop bits
  * **flow0** 0 for none, 1 for XON/XOFF and 2 for RTS/CTS (though these devices may not all support those control lines on the port, very few if any devices will require them but these may not be the best choice if you need that)

Take this command over to your text editor and plug in your own settings before pasting that into the terminal window.

<code>
python3 ./wizconfig.py --device 00:08:DC:xx:xx:xx --nmode0 1 --port0 5000 --baud0 9600 --ka 1
</code>

If you have a second serial port replace the 0 in the above with a 1 and send the command again, or lump them all together in one great big one. The only change is the **ka** value above should be **ra** for the second port.

-----
====Backing Up A Working Config====
It is possible to save all the settings of the card to a single file for backup purposes and then restore from that file later if needed. This generates a filename starting with “getfile" with the MAC address and a file extension of “.log” in the folder with the wizconfig app.

If you have a single port device use the command:

<code>
python3 ./wizconfig.py --device 00:08:DC:xx:xx:xx --getfile cmd_oneport.txt
</code>

and for a two port version the command is:
<code>
python3 ./wizconfig.py --device 00:08:DC:xx:xx:xx --getfile cmd_twoport.txt
</code>

My device has a file that looks like this:

<code>
01) MC: 00:08:DC:75:C9:E8 | MAC address: 00:08:DC:xx:xx:xx
02) VR: 1.3.3             | Firmware Version: 1.3.3
03) MN: WIZ750SR-1xx      | Product Name: WIZ750SR-1xx
04) ST: ATMODE            | Operation status for channel 0: ATMODE
05) UN: RS-232/TTL        | UART Interface(Str) for channel 0: RS-232/TTL
06) UI: 0                 | UART Interface(Code) for channel 0: 0
07) OP: 1                 | Network Operation Mode for channel 0: TCP Server mode
08) IM: 0                 | IP address Allocation Mode: Static IP
09) LI: 192.168.0.97      | Local IP address: 192.168.0.97
10) SM: 255.255.255.0     | Subnet mask: 255.255.255.0
11) GW: 192.168.0.1       | Gateway address: 192.168.0.1
12) DS: 192.168.0.1       | DNS Server address: 192.168.0.1
13) LP: 5000              | Local port number for channel 0: 5000
14) RH: 192.168.11.3      | Remote Host IP address for channel 0: 192.168.11.3
15) RP: 5000              | Remote Host Port number for channel 0: 5000
16) BR: 6                 | UART channel 0 Baud rate: 9600
17) DB: 1                 | UART channel 0 Data bit length: 8-bit
18) PR: 0                 | UART channel 0 Parity bit: NONE
19) SB: 0                 | UART channel 0 Stop bit length: 1-bit
20) FL: 0                 | UART channel 0 Flow Control: NONE
21) PT: 0                 | Time Delimiter for channel 0: 0
22) PS: 0                 | Size Delimiter for channel 0: 0
23) PD: 00                | Char Delimiter for channel 0: 00
24) IT: 0                 | Inactivity Timer Value for channel 0: 0
25) CP: 0                 | Connection Password Enable: 0
26) NP:                   | Connection Password:  
27) SP:                   | Search ID Code:  
28) DG: 1                 | Serial Debug Message Enable: 1
29) KA: 1                 | TCP Keep-alive Enable for channel 0: 1
30) KI: 7000              | TCP Keep-alive Initial Interval for channel 0: 7000
31) KE: 5000              | TCP Keep-alive Retry Interval for channel 0: 5000
32) RI: 3000              | TCP Reconnection Interval for channel 0: 3000
33) EC: 0                 | Serial Command Echoback Enable: 0
34) TE: 1                 | Command mode Switch Code Enable: 1
35) SS: 2B2B2B            | Command mode Switch Code: 2B2B2B
36) CA: 2                 | Type and Direction of User I/O pin A: Analog Input
37) CB: 0                 | Type and Direction of User I/O pin B: Digital Input
38) CC: 1                 | Type and Direction of User I/O pin C: Digital Output
39) CD: 1                 | Type and Direction of User I/O pin D: Digital Output
40) GA: 1307              | Status and Value of User I/O pin A: None
41) GB: 1                 | Status and Value of User I/O pin B: High
42) GC: 0                 | Status and Value of User I/O pin C: Low
43) GD: 0                 | Status and Value of User I/O pin D: Low
44) SC: 11                | Status pin S0 and S1 Operation Mode Setting: DTR/DSR
45) S0: 1                 | Status of pin S0 (PHY Link or DTR): PHY Link Down / The device ready for communication
46) S1: 0                 | Status of pin S1 (TCP Connection or DST): PHY Link Up / The device is not ready
</code>

>Note the 4th line above that says “ATMODE” if you see that it’s a problem. See the troubleshooting section below.

You can re-upload this to a new board via the setfile command passing it this filename. You should edit the file first and change the MAC address to be the proper one for the new card. This may or may not be necessary but why risk messing it up.

-----
====Troubleshooting:====

**Do not be tempted to use the “sp” switch to set a “search identification” name.** Those can be up to 8 characters so can’t hold much anyway. If you set this then the device will no longer show up in a global scan, you will always have to reference it by that name until you clear it. It is helpful to me to be able to do a search and have all the devices on the network be listed in that one place.

**ATMODE** if you have the single port version there is a switch on it labeled “hw-trg” if this is turned on then the port has booted into the mode where you can issue commands via the serial port. If this is on you can connect a serial adaptor to the serial port on the device and do a factory reset by writing to it the Factory Reset command which is “FR” with a carriage return and line feed. I find the easiest way to do this is with the serial console that is part of the Arduino IDE as  you can set the line ending to be both ln and cr and then just type FR<return> I just had to do this to one of them that I had set a search string for and then couldn’t figure out that they didn’t show in a search after that. So this is good to know about if something goes horribly wrong and they aren’t showing up on a network scan. This setting is also shown in the scan output. A functional device should show “open” as in the search portion above. If the device has booted into ATMODE it will show ATMODE instead. To reset turn the switch off and reboot.

-----
====Purchasing:====

You can order these cards directly from the manufacturer, but the shipping from overseas is prohibitively expensive. I would recommend ordering them from Mouser or Digikey and you can find exactly the one  you want but with more reasonable shipping charges and a much faster delivery time. 

The single port version: **WIZ750SR-110**

[[https://mou.sr/3Mjak4m|WIZ750SR-110 from Mouser]]\\
[[https://www.digikey.com/short/3qrnt2vp|WIZ750SR-110 from Digikey]]

The dual port version: **WIZ752SR-125**

[[https://mou.sr/3siDYQ6|WIZ752SR-125 from Mouser]]\\
[[https://www.digikey.com/short/ptfw1qzj|WIZ752SR-125 from Digikey]]

Believe it or not I do not see these for sale on Amazon. And no, those are not affiliate links of any kind. As of this writing Mouser is slightly cheaper that Digikey but that floats around. Check the prices and compare shipping. They are both reliable and reputable companies to order from.