Introduction
This document discusses how to communicate with a server using WebSocket or HTTP protocol. This kind of communication is usually done by web browsers with sites on the internet.
HTTP commands can also control Aximmetry, it is discussed in a separate document here: External Control of Aximmetry via HTTP
WebSocket or HTTP, What is the Difference?
WebSocket is characterized by its low latency and bidirectional communication protocol, allowing data to be transmitted in both directions simultaneously. The connection is established only once, enabling efficient real-time interaction between clients and servers.
In contrast, HTTP operates with a unidirectional communication style. With every request, a new connection needs to be established, leading to increased overhead due to additional headers and metadata. HTTP is well-suited for fetching resources and data from servers in a request-response fashion like in RESTful APIs.
Websocket Client
You can communicate with a server using the Websocket Client module in the Flow Editor.
For easy debugging when setting up your connection, we recommend exposing Websocket Client as a video with the Text Peeker module:
Input Pins
- Connect
Connects to the target server. It must be turned on to send data.
When the module is successfully connected to the server the Connected output pin turns True. - URL
The URL web address of the server, which consists of a protocol prefix and a domain name. Optionally, additional elements such as a port, path, and other suffixes may follow the domain name.
A WebSocket URL's protocol prefix will likely be "ws://" instead of "http://", such as "ws://example.com/socket", where "ws" indicates that the connection should be made using the WebSocket protocol. Keep in mind that this does not imply that URLs with "http://" prefix don't work as WebSockets.
Also, the module supports secure connection, which can be "wss://" where "s" indicates a secure (encrypted) connection, similar to "https://".
NOTE: You can use the URL Compose and URL Decompose modules to easily put together URL addresses or to parse them. - Socket IO Mode
Turn on Socket.IO mode when the targeted server uses the Socket.IO library for communication.
When defining the text for the Data pin, it should be formatted as follows: ["eventname", mydata]
Where the mydata part can be in JSON format. For example: ["message", {"something": "Text", "otherthing": 4.35}].
NOTE: Socket.IO is a JavaScript library that adds several features and enhancements on top of WebSocket communication.
NOTE: Socket.IO does not support Binary mode; it only operates using Socket.IO's WebSocket protocol.
NOTE: Aximmetry's collection data type can be easily converted to JSON using the Collection To JSON module. Subsequently, it can be parsed into the text ["eventname", ] by using the Text Concat Multi module. - Binary Mode
Switches between sending text or byte (binary) data. - Data and Data Bytes
The text or bytes of the message that will be sent to the target server. To use Byte data instead of Text, turn on the Binary Mode pin. - Auto Send and Send
Sending of the message can be performed in two ways. You can send it at a specific time by triggering it via the Send pin. Alternatively, you can turn On Auto Send, in this case, each time the Data value is changed it is sent automatically.
Output Pins
- Received and Received Bytes
The data that is received from the server. To receive Byte data instead of Text, turn on the Binary Mode pin.
When receiving byte data, these modules can convert the data: Bytes To Text, Bytes To Scalar, Bytes To Vector, and Bytes To Integer. - Connected
The Connected output pin is True when the module has established the connection with the target server.
HTTP Request
You can communicate with a server using the HTTP Request module in the Flow Editor.
You can also make an HTTP Request to any webpage on the World Wide Web (like https://www.wikipedia.org/) and you will typically receive the HTML content of the requested webpage.
HTTP Request module uses the GET method to make a request unless the Post pin is turned on.
For easy debugging when setting up your connection, we recommend exposing HTTP Request as a video with the Text Peeker module:
Input Pins
- URL
The URL web address of the server, which consists of a protocol prefix and a domain name. Optionally, additional elements such as a port, path, and other suffixes may follow the domain name. For example: http://www.example.com:8080/path/to/resource
Also, the module supports secure connection, which can be "https://" where "s" indicates a secure (encrypted) connection.
NOTE: You can use the URL Compose and URL Decompose modules to easily put together URL addresses or to parse them. - Headers
Headers convey additional information about the request, the client, or the desired server behavior.
If you are using a server that was made for you, then you probably don't need anything in the header. If you are targeting a server on the World Wide Web, then including relevant headers in your request becomes important for the server to appropriately process and accept your request.
For example:
Accept-Language: en-US,en;q=0.5User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36
Where "User-Agent:" Identifies the user agent making the request. In the above example, we used a user-agent that would be generated by a web browser application. This is needed on some websites as they only accept web browser requests. Some websites even need more in the headers or more complete interactions as they try to deny any traffic that is not coming from web browsers.
"Accept-Language:" Specifies the preferred language for the response. It helps the server decide which language version of the content to send back.
- Post and Post Data
The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.
If you make a POST request, the server might respond with various types of content, depending on the application's design. It could be HTML if the server is responding with a new webpage, but it could also be JSON, XML, or other data formats. In the case of JSON and XML, you can parse the text into █ Collection pin data type using the JSON Text or XML Text module. - Request
Sends the request message to the target server. Alternatively, you can turn on Auto Request, see below: - Auto Request and Auto Interval
Auto Request sends requests periodically, the length of the period is determined by the Auto Interval pin in seconds.
Output Pins
- Text
The text data that is received from the server. - Image
The image data that is received from the server. - Type
The format in which the Text or the Image data were received.
Testing and Examples
If the received data is a long text you can use the Text Image module instead of the Text Peeker to write out a long formatted text:
If the response is in an HTML format, then you can easily save the received HTML with the Text Exporter module in the .html file extension.
Then you can open this file with any web browser. This way you can easily see if you get the same response as you would get with a web browser.
NOTE: In the screenshot above, we added a Text Changed module and turned off the Auto Numbering pin in the Text Exporter module. This ensures that the exported HTML file is overwritten when a new HTML text is received. This way when the HTML file is opened in your browser and you receive a new HTML text in Aximmetry, you only need to refresh (F5) in the web browser to see it.
There are two examples in the Tutorials package of using HTTP Request on RSS feeds: [Tutorials]:MOS\Crawl\Crawl_RSS_Vertical_Subtext.xcomp and [Tutorials]:MOS\Crawl\Crawl_RSS.xcomp
NOTE: Since RSS feeds are always formatted in XML, you can easily process any RSS feed in the Collection data structure by first using the XML Text module on the received text.
