Introduction
Anyone Can Use It
If you have ever used a web browser to surf the internet or check your Facebook, you will be able to use the WiNet. The WiNet Gateway is a stand-alone web server that allows you to control wireless relays using the web pages inside the WiNet Gateway. The WiNet allows you to control up to 16 wireless relay boards each capable of controlling 512 relays simply from a tab in your browser or smartphone. Combined with our link.signalswitch.com service, which gives you global internet-based access to our network device, this gives you internet based access to control hundreds of relays using any computer, Android Device, iPhone or iPad, or really any device with network access and a browser.
Easy Customization
For those who need to rebrand the product or add custom controls that the My Page doesn’t have the flexibility to allow, the entirety of the front end is written in HTML, CSS, and JavaScript. This means that just about any web developer will be able to change not only the look and feel of the web pages displayed through the browser, but also how they function. For instance, you could create a simple button that checked to see if a sensor connected to the board was within a certain range and if it isn’t then activate a relay.
Talk to 802.15.4 with an HTTP request or TCP Socket
If you don’t want to use a web browser to control the relays and would prefer to write your own software, the WiNet has two simple ways to give network and internet based HTTP Requests and TCP Socket communications to our relay controllers. How this works is that you send your request or open your socket to the WiNet and it will forward your commands to the specified board.
HTTP Request
The WiNet supports making HTTP requests directly to it. This allows you to use any of the gateways we have made for use on the built-in web page or allows you to write a script and access that via HTTP. This includes our runcommand.sh which allows you to send up to three commands in one request, our getAdReading.py gateway which allows you to read the A/D inputs on a board and convert them to real world values based on how you configure them, and getDeviceList.cgi which allows you to get a list of all devices configured for the board and some general purpose information on them. This method will be slower than a direct TCP socket, but provides a higher level interface which is much easier to use.
This means it could be as simple as emailing someone a link that they can click to turn on or off a relay or read sensor inputs. It is the recommended way to write applications to communicate with a WiNet Gateway. Almost every programming language has an entire HTTP request library and the protocol is very well documented so development for this route should be much faster.
TCP Socket
TCP sockets are low level two-way network communication tunnels that allow a client to open a connection to a server. Once the connection is established data can be passed freely between the client and server.
How this works for the WiNet is that when you configure a device from the WiNet’s Device List Configuration web page you will notice a port number associated with that device. In the programming language or TCP Client software of your choice simply open a socket to the WiNet’s IP Address and use the port number associated with the board that you want to control. This socket will have all of the data that is sent over its output buffer forwarded to the desired board and all of the return data that the board sends back will be forwarded back over using the input buffer of the socket.
Quick Reference
Telnet Port: 23
Telnet Username: ubuntu
Telnet Password: temppwd
FTP Port: 21
FTP Username: ubuntu
FTP Password: temppwd
Web Page Login Username: winet
Web Page Login Password: User Configurable
Getting Started
Things You Will Need
- WiNet Gateway
- Straight through Ethernet cable
- 5v DC Power supply
- DHCP enabled router (this is the standard setting for routers)
- Any device with a web browser and access to the network the WiNet is on
- A ProXR, ProXR Lite, or Fusion series relay controller with one of the following interface:
- WiFi
- Ethernet
- Web-i
- 802.15.4
Connecting the WiNet to the Network
The WiNet has an Ethernet port onboard. Simply connect this port to your router using a standard Ethernet cable (not a crossover) and connect a regulated 5v DC power supply. It is important for the WiNet to be connected to a DHCP enabled router during initial setup as by default it is running in DHCP mode until you specify otherwise in the configuration pages. DHCP is the default setting for most standard routers so this shouldn’t be a problem unless you are on a highly maintained network.
Finding the Device
Base Station is our software suite which allows you to control any of our devices through one application. Today however you will only need it to find the WiNet device’s IP Address on your Local Area Network. It can be found at ncd.io/start.
After running Base Station, click the “Network” radio button. The WiNet Gateway should be discovered in the list after a couple of minutes. Double click on the WiNet gateway to open a web browser interface to the user interface.
WiNet Interface
Once on the home page of the WiNet, select the Configure link in the bottom right hand side of the page and you will be taken to a page that lists all of your associated devices and lets you add new ones by simply selecting “Add New Device” under the desired communication section.
Adding an 802.15.4 Device
Select the “Add New Device” under the header “802.15.4 Device List”. A box will show that prompts you for the lower serial number of the 802.15.4 module.
You can find the lower serial number on the bottom of the 802.15.4 Module installed on your relay board.
The lower serial number will start with a 409 and can be found below the upper serial.
Once you find this serial number enter it into the input field and select “Save Device” and you will be taken to the Device Configuration page.
Skip to the section titled “Configuring Your Relay Controller”.
Adding a Network device
Insure that the device you wish to add is connected to your network and powered up.
Select the “Add New Device” button under the header “Network Device List”. A box will appear that displays a list of all of the NCD network devices that are not yet configured for the WiNet. Select the desired one and you will be taken to the Device Configuration page.
It is highly recommended that you log into your router or contact your network administrator and ensure that the device you are adding has a static IP Address so that you will not lose communications with it.
Configuring your relay controller
When you add the new device you will be taken to the Device Configuration Page. From here you can name the relay controller, give it an address, set the default home page for the device (which page will automatically be opened when you select it from the device list), and change the series of the device.
Along the top of this page you will see two additional links “Relay Configuration” and “A/D Configuration”. Select “Relay Configuration”.
The Relay Configuration page allows you to change how many banks of relays this relay controller has. It also allows you to name each individual bank and relay. Each bank is configured separately so you will need to do them one at a time and select the “Update” button before moving to the next.
Name your relays and banks whatever you would like.
Once this is done if you are going to be using A/D inputs, select “A/D Configuration” at the top of the page.
This page allows you to change the names that will be displayed for the A/D inputs of the board and the rate at which the inputs will refresh. We do not recommend you set the rate of the A/D refresh below 3.
In addition you can choose to have the A/D values reported by the board be converted into real world values by using a sensor in the drop down lists under the section titled “A/D Sensor Conversion Configuration”. If your sensor is not listed here it is possible to create a custom sensor item which will convert your readings. We will talk more about this later in the guide.
Make the changes you would like to and make sure to select “Update” and your device should be completely configured to your preferences.
Controlling your device
In the left navigation choose the button titled “Device List”.
Now you should see the board you just configured listed on this page. Select this device and you will be taken to its control page. Depending on the settings you chose you will be taken to the Relay Control page, the A/D Inputs page, or the Console page. For the sake of this guide select the button titled “Relays” in the left navigation of this page.
This page allows you to turn on and off the relays using the buttons titled “On and “Off”. You can also turn all relays in a bank on and off by using the “All On” and “All Off” buttons. You can refresh the status of the relays on a specific bank by using the “Refresh” Button in the section that contains your bank name. You can change the currently selected bank by selecting the bank name of the desired bank.
In the upper left hand side of the page select the button titled “A/D”.
This page will allow you to view the values of the A/D inputs. They will be reported at the intervals specified in the A/D Configuration page. It will also convert the A/D readings into real world values based upon the configuration you set for the inputs on the A/D Configuration page.
In the left hand side of this page select the button “Console”.
This page allows you to send custom commands easily to the relay controller. These can be any types of commands you would like as long as they are in the command set of the series of the board. If the command will return more than one byte you will need to change the input under the section titled “Bytes server will return” to the appropriate number of bytes.
For the syntax of the command read the instructions on the page.
Advanced WiNet Configuration
Device List Configuration
Go back to the Device List page and in the lower right hand select “Configure”.
In both the Network Device List and the 802.15.4 Device List for each device that is configured a TCP Port number is listed under the column titled “TCP Port:”. This port number is not the port number that the network device is listening on. It is the port that is used to open a socket to it through the WiNet. For instance if you wanted to open a TCP socket to an 802.15.4 module you would open the socket using the IP Address of the WiNet using the port number listed here as the port number of the socket. All information passed to the WiNet over this socket will be forwarded to the 802.15.4 relay controller and the response from the board will be forwarded back over the socket.
In the Network Device List there is a column for the IP Address of the relay controller. If the IP Address of the board changes, it will need to be updated to the new IP Address here.
In both the Network Device List and the 802.15.4 Device List there is a column titled “Command Timeout” this is the period of time the WiNet will wait for a response from the specific device before it considers the command failed and will return any data it has received from the device. Usually if it does return any bytes and it still waits the full timeout it means that the runcommand.sh string was told to expect too many bytes in the r section of the command argument. More can be learned about this later in the guide.
WiNet Settings Configuration
In the left hand side of the screen select “WiNet Settings”.
This page allows you to change WiNet Settings such as the IP Address, the Remote Server address and port number, and the password.
We recommend that you make the WiNet use a static IP Address so that you will have fewer problems connecting to the board both locally and remotely. You can change the IP Address settings from the section titled “Set your IP Address Configuration for the WiNet”.
The “Remote Server Configuration” section lets you change the server that the WiNet sends its connection information to. It is not recommended to change this unless you don’t want to access this device from link.signalswitch.com or if you have your own central server you would like to receive information on. The port 8080 is the port that should be used from an external source to access the WiNet. For instance you would set up the router that the WiNet is attached to so that it forwards incoming requests on port 8080 to port 80 on the WiNet.
To set up a password for the device simply select the checkbox in the area titled “Set Up the Password for the Device” and input your desired password. The username that this password will accompany is WiNet. Again if you desire a password you will need to use the username WiNet.
My Page
My Page is a page that we have built that allows you to quickly and easily create custom button that will send up to three commands of your choosing to any boards that are configured for the WiNet. This means you can control up to three boards from one button. These can be timers, relay control commands, A/D readings, etc. Simply name the button and assign some commands.
Configuration
The first thing you will need to do is configure the My Page to do as you’d like. To do this go into the Configuration section of the WiNet (Select “Configure” in the bottom right of the device list page) and choose My Page Config in the left hand side of the screen.
From this page you can change the title of My Page, change where and if the link to My Page appears on the Device List, and add custom functionality to the WiNet’s My Page via the use of custom commands in buttons.
To change the Title simply enter in the desired title of the page in the input marked “Title of My Page”. Select Update after it has changed to save changes.
To change where and if the My Page shows up, select the option you would like from the displayed list. Select Update after this has been changed to save changes.
To add functionality to a custom button simply name the button, type in the commands the button will send, change the Bytes Back field to represent how many bytes that command will send back, the Command Timeout to how long you would like to give the controller to respond, the Wait Time to how long you would like to wait before issuing the next command, and select a device that you would like the command to target from the Target Device dropdown lists. This dropdown list will only display devices that have been configured for the WiNet.
Control
To access the My Page you will need to make sure that you didn’t choose the option “I don’t want the My Page link to appear” option on the My Page Config page.
Simply go to the Device List page and a link will appear either on the top of the Device List or the Bottom of the device list depending on which options you chose during My Page Configuration. Select the link and you will be taken to the My Page. From here simply select the custom button you want to trigger and the return bytes will be displayed to you.
Connection to the WiNet
You can connect to the WiNet over a Local Area Network (LAN) or over the internet depending on how you and your WiNet are connected to the internet. If you or your WiNet do not have access to the internet then you will not be able to access the WiNet remotely (over the internet). If you are on the same network (have the same external IP Address) as the WiNet then you will not be able to access it remotely.
Local Area Network Connection
This is the easiest and fastest way to connect to your WiNet. It requires you to be on, or at least connected to, the same network as the WiNet. Simply run the NCD Base Station software and the WiNet will appear in the “Discovered Network Devices” section of this software. Simply double click on the corresponding device that appears here. You will be taken to your browser and to the IP Address of the WiNet. You should land on the Device List page.
Remote Connection
Remote connection implies that you are connecting to this device over the internet.
For this to work it will be required of you to set up port forwarding on your router. This is because without port forwarding the router doesn’t know if the requests you are sending it are legitimate or if you are just a random internet server blasting it with requests trying to get past its firewall. By default you should forward incoming requests to your router on port 8080 to the IP Address or MAC Address of your WiNet on port 80. So anytime a request comes in on port 8080 to your router it will be forwarded automatically to your WiNet.
We have a server at link.signalswitch.com/macAddress where macAddress is the MAC Address of your WiNet that will forward you to the IP Address of your network. Basically what this means is that if you went to link.signalswitch.com/macAddress then it would redirect you to the external IP Address of your network with a port number (port 8080 by default) that should allow you access to the WiNet. This service will be very useful for establishing a connection over the internet especially if your network does not have a static IP Address.
WiNet Gateway APIs
The WiNet Gateway has a list of programs and modules that will allow you to do just about anything you need to do in the WiNet using a simple HTTP request. This allows almost every programming language a high level interface into the inner workings of the WiNet.
In the following ipAddress is meant to denote the IP Address of your WiNet. In practice replace ipAddress with the IP Address of your WiNet if on a local area network
getAdReading.py – This gateway queries the board for all eight A/D inputs and runs them through a conversion process if the corresponding input has been configured for real world conversion values.
This gateway expects a ? followed by a random number followed by a : symbol and the identifier of the board (MAC Address or Lower Serial number) followed by a comma and then the interface (802154 or network).
Example: http://ipAddress/cgi-bin/getAdReading.py?208:00204af4214d,network
getAnyEtc.sh – This gateway pulls in a specific configuration file located in the /mnt/flash/etc directory allowing you to display its contents or use them in the javascript of the front end.
This gateway expects a ? followed by a random number followed by a : symbol and then the path to the desired file.
Example: http://ipAddress/cgi-bin/getAnyEtc.sh?448:/network/00204af4214d/homepage
getDeviceList.cgi – This gateway pulls in a delimited text that contains general information about all of the devices that are configured for the WiNet. Each device will return its MAC Address or Lower Serial number followed by a ~ followed by its name, followed by : and the address information. After the address information is finished, each field in the address is delimited by a : there follows a ~ and then the default folder of the homepage of that device. After the a : symbol is shown followed by the default homepage followed by a ~ and then the port number associated with the relay controller. Finally there is another ~ followed by the interface.
This gateway expects a ? followed by a random number.
Example: http://ipAddress/cgi-bin/getDeviceList.cgi?448
getMyPageInformation.py – This gateway pulls in all of the custom buttons on the My Page including the title of the My Page.
Example: http://ipAddress/cgi-bin/getMyPageInformation.py
getRelaysInformation.py – This gateway pulls in all of the information required for relay control including the default timeout, number of banks, the device name, its address, and all the bank names and relay names associated with that device.
This gateway expects a ? followed by a random number and a : then the identifier of the board (MAC Address or Lower Serial Number) and then a comma and the interface type (802154 or network).
Example:
http://ipAddress/cgi-bin/getRelaysInformation.py?214:00204af4214d,network
postAnyEtc.py – This gateway allows you to make POST requests to the server to save large configuration files.
This gateway expects a data field for the data to be passed for saving and a targetFile field which will contain the folder path and file name of the file to be saved in the /mnt/flash/etc folder.
Example:
$.post(“/cgi-bin/postAnyEtc.py”,
{
data: sensorStringToPost,
targetFile: “/network/00204af4214d/adConversionInputs”
},
function (data, status) {
location.reload();
}
);
runcommand.sh – This gateway allows you to send commands to a specific device using an identifier of the lower serial number or the MAC Address of the desired module. This can either be a single command or up to three commands.
This gateway expects a ? followed by a random number and a : and cmd= followed by the command you would like to send. After that you will need an r followed by the number of bytes you expect the command to return. After this you will need a t followed by the timeout which is how long you want the WiNet to wait for a command from the targeted device. This will be followed by a w and how long you would like the command to wait before sending the next command in the series. Finally use id followed by the identifier for the board. The identifier will be either the MAC Address or the Lower Serial number of the target module. If another command is desired use a : and then use the same syntax used earlier from the cmd= onward.
Example Single Command:
http://ipAddress/cgi-bin/runcommand.sh?573:cmd=254,130,1r1t1000w0id00204af4214d
Example Triple Command:
http://ipAddress/cgi-bin/ runcommand.sh
?573:cmd=254,130,1r1t1000w0id00204af4214d:cmd=254,124,1r1t1000w0id00204af4214d:cmd=254,33r1t1000w0id00204af4214d
setAnyEtc.sh – This gateway allows you to override or create a new configuration file in the /mnt/flash/etc folder of the WiNet.
This gateway is expecting a ? symbol followed by a random number. This is followed by the folder path and file name of the target file and a : symbol. After that just throw on whatever information you want saved into the file.
Example Single Command:
http://ipAddress/cgi-bin/setAnyEtc.sh?573:/
Using the WiNet Gateway APIs
There are three ways you can use the WiNet Gateway APIs. The first is to enter the gateway and its required arguments into the url bar of your browser and it will return a web page with the desired response if everything was entered correctly. The second way is to use an HTTP Request using Ajax. This will mostly be used from the web pages themselves. The third way is HTTP requests from external software outside of the WiNet. This includes from external servers, software, and devices. We will go over each one of these a little further.
Direct URL Entry
Direct URL entry is the method of entering the IP Address, /cgi-bin/, and API information directly into the URL bar of your browser.
*Insert Picture
This should mainly be used to test the WiNet APIs and their responses. It can also be used for simple tasks such as emailing someone
About Ajax
Ajax stands for asynchronous JavaScript and XML. We use this technology to pass information to specific APIs on the WiNet itself. This allows us to access server data and controls using a web page.
There are two main types of Ajax requests, GET and POST. Almost all of our WiNet APIs rely on GET requests so that is what we will focus on in this section.
In the WiNet we use the jQuery plug-in to make ajax requests. We recommend this plug-in because it not only allows us to make Ajax requests but gives us additional functionality for the front end.
The following is a simple example of how to make an Ajax GET request.
$.get(
“/cgi-bin/getAnyEtc.sh?” + Math.floor(Math.random() * 1000) + “:/” + deviceComms + “/” + deviceSerial + “/deviceNameAddress”,
{},
function (responseText) {
var response = decodeURI(responseText || “no response text”);
alert(response);
},
“html”
);
In the above example we start off with $.get. This tells the web browser to access the get function in the jQuery library ($ is shorthand for jQuery). After that we pass it the location of the program we are accessing and the arguments that program is expecting.
Now it will fire off the request to the server while we are defining what we will do when the data is returned. In this example we are simply saying decode the responseText that we got back from the Ajax request and assign it to the variable response. If there is no response from the Ajax request assign the string no response text to response. After response is assigned a value simply throw up an alert dialog box to display the value of response.
In a real application you would probably want to display the response as content of the page or run some logic routines on the response to ensure that the action you wanted was taken by the server.
Access from External Software
Accessing the WiNet APIs from an external software source still requires an HTTP Request however, most languages have a built in way to do this in the background similarly to an AJAX Request. Below is an example Java snippet of code that makes such an HTTP Request and returns the data.
//This is the string sent to the controller. This particular string should turn on //relay 1.
String url = “http://192.168.0.15:80/cgi-bin/runcommand.sh?524:cmd=254,108,1r1t1000w0dl4092f1ba”;
URL obj = new URL(url);
//URL Connection, essentially a socket for sending and receiving data.
HttpURLConnection urlConnection = (HttpURLConnection) obj.openConnection();
urlConnection.setRequestMethod(“GET”);
//This responseCode will be used to determine if the http request was successful.
int responseCode = urlConnection.getResponseCode();
//Check for valid connection
if(responseCode == HttpURLConnection.HTTP_OK){
//Create inputStream object for reading data returned by device
BufferedReader inputStream = new BufferedReader(new InputStreamReader(urlConnection.getInputStream()));
//Create a String object to temporarily store data back from object.
String returnData;
//StringBuffer object for holding all data returned by the device
StringBuffer response = new StringBuffer();
//Continously read data back from controller untill there is none left
while((returnData = inputStream.readLine())!= null){
response.append(returnData);
}
inputStream.close();
}
Adding and Editing Scripts and Pages
You can add or edit scripts and pages using FTP to download and upload files to and from the server. Simply use your favorite FTP Client and connect to the WiNet over port 21. When asked for login credentials use:
Username: ubuntu
Password: temppwd
Once logged in you can move files to and from the WiNet at will. Refer to the documentation of your FTP Client to learn more about how to use it.
We recommend using FileZilla as the FTP Client.
Adding a Script
The scripts are located in the cgi-bin directory of the WiNet. You can find this directory at /usr/lib/cgi-bin. Scripts uploaded to this directory can be accessed using the web site by referencing the /cgi-bin/scriptName.
These scripts can do anything that normal scripts without root access can on a Linux based OS.
The scripting options are Shell, Python, and Perl.
For information on how to write a script with these languages refer to the documentation for the desired language.
Adding a HTML Page
The HTML pages are located in the www directory. The full path to this directory is /var/www. Simply upload a file to this directory or one of its subdirectories and it will be accessible using a web browser.
The pages that come with the WiNet are all written in a mixture of plain HTML, Javascript, jQuery, and CSS. You can use the existing pages on the WiNet and the information found in this guide as a reference on how to build your own pages to communicate with relays.