Added documentation for Ethernet #27
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
manthanand
commented
Jun 19, 2022
Docs/source/Software/drivers.rst
Outdated
| Ethernet Queue and sends through Ethernet - if there is no connection, it calls ``Ethernet_ConnectToServer()``. ``Ethernet_SendMessage()`` returns pdFalse | ||
| if the Queue is empty and pdTrue if the Queue is not empty. The struct EthernetMSG_t will hold the data packets of either information | ||
| regarding IMU, GPS, or CAN. The struct consists of an id enum, length, and a union of data. Since the data is in a union, there will be zero padding | ||
| at the MSB. |
There was a problem hiding this comment.
You don't actually talk about how to use the driver in this documentation. There isn't any mention of Ethernet_PutInQueue which is what actually allows the layers above to put messages in the queue. Most of these just discuss what the functions are, not how to use them.
| The sunlight is the client while data acquisition is the server | ||
|
|
||
| Usage | ||
|
|
||
|
|
||
| ``Ethernet_Init()`` must be called first as a way to create the Ethernet Queue and create a socket when a connection has been established. | ||
| Within the function, ``Ethernet_Init()`` calls the blocking function ``Ethernet_ConnectToServer()`` which is responsible for setting the ``servsocket`` variable to the corresponding socket value. |
There was a problem hiding this comment.
You don't really say what the servsocket variable is so you should either add what it is used for or just remove that part of the sentence. This prevents documentation from being unnecessarily wordy.
|
|
||
| ``Ethernet_Init()`` must be called first as a way to create the Ethernet Queue and create a socket when a connection has been established. | ||
| Within the function, ``Ethernet_Init()`` calls the blocking function ``Ethernet_ConnectToServer()`` which is responsible for setting the ``servsocket`` variable to the corresponding socket value. | ||
| After ``Ethernet_Init()`` has finished completing, ``Ethernet_SendMessage()`` is called repeatedly. ``Ethernet_SendMessage()`` is a blocking function which waits until there is data in the queue to send that data across ethernet. |
There was a problem hiding this comment.
Suggested change
| After ``Ethernet_Init()`` has finished completing, ``Ethernet_SendMessage()`` is called repeatedly. ``Ethernet_SendMessage()`` is a blocking function which waits until there is data in the queue to send that data across ethernet. | |
| After ``Ethernet_Init()`` has finished, ``Ethernet_SendMessage()`` is called repeatedly. ``Ethernet_SendMessage()`` is a blocking function which waits until there is data in the queue to send that data across ethernet. |
|
|
||
| ``Ethernet_Init()`` must be called first as a way to create the Ethernet Queue and create a socket when a connection has been established. | ||
| Within the function, ``Ethernet_Init()`` calls the blocking function ``Ethernet_ConnectToServer()`` which is responsible for setting the ``servsocket`` variable to the corresponding socket value. | ||
| After ``Ethernet_Init()`` has finished completing, ``Ethernet_SendMessage()`` is called repeatedly. ``Ethernet_SendMessage()`` is a blocking function which waits until there is data in the queue to send that data across ethernet. |
There was a problem hiding this comment.
This isn't a blocking function. Also, although you say that it sends the messages that are in the queue, you don't say how to put messages in the queue.
| Within the function, ``Ethernet_Init()`` calls the blocking function ``Ethernet_ConnectToServer()`` which is responsible for setting the ``servsocket`` variable to the corresponding socket value. | ||
| After ``Ethernet_Init()`` has finished completing, ``Ethernet_SendMessage()`` is called repeatedly. ``Ethernet_SendMessage()`` is a blocking function which waits until there is data in the queue to send that data across ethernet. | ||
| The data that is sent across Ethernet is in a struct called EthernetMSG_t which contains specific information of either IMU, GPS, or CAN type. | ||
| The struct consists of an id enum, length, and a union of data regardless of the type of data. |
There was a problem hiding this comment.
I would get rid of the last line, the zero padding is indeterminate based on the compiler used. Also anyone should be able to read the header file and figure it out.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.