Merge pull request #4 from chipkin/readability

ssmethurst · web-flow · commit e779905be6e7 · 2020-06-19T15:01:21.000-07:00
Updated readme and comments
diff --git a/BACnetServerMSTPExample/BACnetServerMSTPExample.cpp b/BACnetServerMSTPExample/BACnetServerMSTPExample.cpp
@@ -1,5 +1,17 @@
-// BACnetServerMSTPExample.cpp : This file contains the 'main' function. Program execution begins and ends there.
-//
+/*
+ * BACnet Server MSTP Example C++
+ * ----------------------------------------------------------------------------
+ * BACnetServerMSTPExample.cpp
+ * 
+ * In this CAS BACnet Stack example, we create a minimal BACnet MSTP server.
+ *
+ * More information https://github.com/chipkin/BACnetServerMSTPExampleCPP
+ * 
+ * This file contains the 'main' function. Program execution begins and ends there.
+ * 
+ * Created by: Steven Smethurst
+*/
+
 
 #include "CASBACnetStackAdapter.h"
 #include "CASBACnetStackExampleConstants.h"
@@ -67,12 +79,13 @@ void APDUCallBack(unsigned char* buffer, uint16_t length, unsigned char source);
 void MSTPFrameCallBack(uint8_t* buffer, uint16_t length); 
 void MSTPDebugLog(const char* message);
 
-// Helper
+// Helper functions
 void DebugMSTPFrame(uint8_t* buffer, uint16_t length);
 
 std::map<std::string, uint32_t> g_statCounter;
 void printMSTPStats(); 
 
+// MSTP Frame
 struct MSTPAPDUFrame : public MSTPFrame
 {
 	MSTPAPDUFrame(uint8_t destination, uint8_t* buffer, uint16_t length) {
@@ -131,8 +144,6 @@ int main(int argc, char* argv[])
 	}
 
 
-
-
 	// 1. Load the CAS BACnet stack functions
 	// ---------------------------------------------------------------------------
 	std::cout << "FYI: Loading CAS BACnet Stack functions... "; 
@@ -143,6 +154,7 @@ int main(int argc, char* argv[])
 	std::cout << "OK" << std::endl;
 	std::cout << "FYI: CAS BACnet Stack version: " << fpGetAPIMajorVersion() << "." << fpGetAPIMinorVersion() << "." << fpGetAPIPatchVersion() << "." << fpGetAPIBuildVersion() << std::endl;
 
+
 	// 2. Connect the serial resource
 	// ---------------------------------------------------------------------------
 	std::cout << "FYI: Connecting serial resource to serial port. baudrate=[" << g_database.device.baudRate << "], ... ";
@@ -153,21 +165,24 @@ int main(int argc, char* argv[])
 	}
 	std::cout << "OK" << std::endl;
 
-	// Configure the highspeed timer. 
+	// Configure the highspeed timer
 	CHiTimer_Init();
 	
 	// Configure the MSTP thread 
 	if (!MSTP_Init(RecvByte, SendByte, ThreadSleep, APDUCallBack, TimerReset, TimerDifference, g_database.device.macAddress, MSTPFrameCallBack, MSTPDebugLog)) {
 		std::cerr << "Error: Failed to start MSTP stack" << std::endl;
 		return 0;
 	}
+	
+	// Set the baud rate
 	MSTP_SetBaudRate(g_database.device.baudRate);
 	std::cout << "OK, Connected to port" << std::endl;
 
 	// Set the MSTP stack's max master 
 	MSTP_SetMaxMaster(g_database.device.maxMaster);
 
-	// 3. Setup the callbacks. 
+
+	// 3. Setup the callbacks
 	// ---------------------------------------------------------------------------
 	std::cout << "FYI: Registering the callback Functions with the CAS BACnet Stack" << std::endl;
 
@@ -186,7 +201,8 @@ int main(int argc, char* argv[])
 	// Set Property Callback Functions
 	fpRegisterCallbackSetPropertyReal(CallbackSetPropertyReal);
 
-	// 4. Setup the BACnet device. 
+
+	// 4. Setup the BACnet device 
 	// ---------------------------------------------------------------------------
 	std::cout << "Setting up server device. device.instance=[" << g_database.device.instance << "]" << std::endl; 
 
@@ -195,13 +211,16 @@ int main(int argc, char* argv[])
 		std::cerr << "Failed to add Device." << std::endl;
 		return false;
 	}
+
+	// Add AnalogValue object to device
 	if (!fpAddObject(g_database.device.instance, CASBACnetStackExampleConstants::OBJECT_TYPE_ANALOG_VALUE, g_database.analogValue.instance)) {
 		std::cerr << "Failed to add Analog value(2)." << std::endl;
 		return false;
 	}
 	std::cout << "Created Device." << std::endl;
 
 	// Enable services 
+	// Enable write property
 	std::cout << "Enabling WriteProperty service... ";
 	if (!fpSetServiceEnabled(g_database.device.instance, CASBACnetStackExampleConstants::SERVICE_WRITE_PROPERTY, true)) {
 		std::cerr << "Failed to enabled the WriteProperty" << std::endl;
@@ -223,12 +242,14 @@ int main(int argc, char* argv[])
 	std::cout << "FYI: Sending I-AM broadcast" << std::endl;
 	uint8_t connectionString[1] = { 0xFF };
 	if (!fpSendIAm(g_database.device.instance, connectionString, 1, CASBACnetStackExampleConstants::NETWORK_TYPE_MSTP, true, 65535, NULL, 0)) {
-		std::cerr << "Unable to send IAm broadcast" << std::endl ; 
+		std::cerr << "Unable to send I-Am broadcast" << std::endl; 
 		return false;
 	}
 
+	// Clear the RX TX Buffer
 	RS232_flushRXTX(g_database.device.serialPort);
 
+
 	// 5. Start the main loop
 	// ---------------------------------------------------------------------------
 	std::cout << "FYI: Entering main loop..." << std::endl;
@@ -266,12 +287,12 @@ uint16_t CallbackReceiveMessage(uint8_t* message, const uint16_t maxMessageLengt
 	if (g_incomingFrame.size() <= 0) {
 		// Call Sleep to give some time back to the system
 		Sleep(1);
-		return 0; // Nothing recived. 
+		return 0; // Nothing received
 	}
 
 	for (std::list<MSTPAPDUFrame>::iterator itr = g_incomingFrame.begin(); itr != g_incomingFrame.end(); itr++) {
 		if ((*itr).length > maxMessageLength) {
-			// This is too big to fit in the message buffer. it probably never will be able to be used. lets get ride of it 
+			// This is too big to fit in the message buffer. It probably never will be able to be used, so get rid of it.
 			g_incomingFrame.erase(itr);
 			return 0;
 		}
@@ -541,8 +562,8 @@ bool SendByte(unsigned char* byte, uint16_t length) {
 }
 
 // The MSTP thread does not need attention for the next "length" amount of time. 
-// This function can do nothing, and the MSTP thread will consumed as much proccessing power 
-// that you will give it. 
+// This function can do nothing, and the MSTP thread will consume as much processing power 
+// as you give it.
 void ThreadSleep(uint32_t length) {
 	if (length < 1) {
 		return;
@@ -555,7 +576,7 @@ void TimerReset() {
 	CHiTimer_Reset();
 }
 
-// Find the differen in time between the last time that the TimerReset was called and now. 
+// Find the difference in time between the last time that the TimerReset was called and now. 
 uint32_t TimerDifference() {
 	return CHiTimer_DiffTimeMicroSeconds();
 }
@@ -573,6 +594,7 @@ void MSTPDebugLog(const char* message) {
 	#endif // MSTP_DEBUG
 }
 
+// Displays MSTP Frame Data
 void DebugMSTPFrame(uint8_t* buffer, uint16_t length) {
 	if (length < 3) {
 		return;
diff --git a/BACnetServerMSTPExample/CASBACnetStackExampleConstants.h b/BACnetServerMSTPExample/CASBACnetStackExampleConstants.h
@@ -1,9 +1,19 @@
+/*
+ * BACnet Server MSTP Example C++
+ * ----------------------------------------------------------------------------
+ * CASBACnetStackExampleConstants.h
+ * 
+ * This is a fully static class that contains all the constants used by the example
+ * This includes Object Types, Property Identifiers, etc
+ * 
+ * Created by: Steven Smethurst
+*/
+
 #ifndef __CASBACnetStackExampleConstants_h__
 #define __CASBACnetStackExampleConstants_h__
 
 /*
-This is a fully static class that contains all the constants used by the example
-This includes Object Types, Property Identifiers, etc
+
 */
 class CASBACnetStackExampleConstants {
 
diff --git a/BACnetServerMSTPExample/CASBACnetStackExampleDatabase.cpp b/BACnetServerMSTPExample/CASBACnetStackExampleDatabase.cpp
@@ -1,3 +1,13 @@
+/*
+ * BACnet Server MSTP Example C++
+ * ----------------------------------------------------------------------------
+ * CASBACnetStackExampleDatabase.cpp
+ * 
+ * Sets up object names and properties in the database.
+ * 
+ * Created by: Steven Smethurst
+*/
+
 #include "CASBACnetStackExampleDatabase.h"
 
 #include <time.h> // time()
diff --git a/BACnetServerMSTPExample/CASBACnetStackExampleDatabase.h b/BACnetServerMSTPExample/CASBACnetStackExampleDatabase.h
@@ -1,18 +1,24 @@
-#ifndef __CASBACnetStackExampleDatabase_h__
-#define __CASBACnetStackExampleDatabase_h__
-
 /*
-The CASBACnetStackExampleDatabase is a data store that contains the
-some example data used in the BACnetStackDLLExample.
+ * BACnet Server MSTP Example C++
+ * ----------------------------------------------------------------------------
+ * CASBACnetStackExampleDatabase.h
+ * 
+ * The CASBACnetStackExampleDatabase is a data storage that contains 
+ * some example data used in the server example. This data is represented by BACnet 
+ * objects for this server example. There will be one object of each type currently 
+ * supported by the CASBACnetStack.
+ * 
+ * The database will include the following:
+ *	- present value
+ *	- name
+ *	- for outputs priority array (bool and value)
+ * 
+ * Created by: Steven Smethurst
+*/
 
-This data is represented by BACnet objects for this server example.
-There will be one object of each type currently supported by the CASBACnetStack.
 
-The database will include the following:
-	- present value
-	- name
-	- for outputs priority array (bool and value)
-*/
+#ifndef __CASBACnetStackExampleDatabase_h__
+#define __CASBACnetStackExampleDatabase_h__
 
 #include <string>
 #include <vector>
diff --git a/BACnetServerMSTPExample/CHiTimer.cpp b/BACnetServerMSTPExample/CHiTimer.cpp
@@ -5,7 +5,7 @@
    Written by:   Steven Smethust 
    Email:        funvill@funvill.com 
    
-   No warrantee of any kind, express or implied, is included with this
+   No warranty of any kind, express or implied, is included with this
    software; use at your own risk
    
    If you find this code useful, credits would be nice!
@@ -16,7 +16,7 @@
 
  Versions
  1.00aA  25 Nov 02 SWS  Created
- 1.00aB  11 Ded 06 SWS  Added Licence 
+ 1.00aB  11 Ded 06 SWS  Added License 
 
 ********************************************************************************/
  
diff --git a/BACnetServerMSTPExample/CHiTimer.h b/BACnetServerMSTPExample/CHiTimer.h
@@ -5,7 +5,7 @@
    Written by:   Steven Smethust 
    Email:        funvill@funvill.com 
    
-   No warrantee of any kind, express or implied, is included with this
+   No warranty of any kind, express or implied, is included with this
    software; use at your own risk
    
    If you find this code useful, credits would be nice!
@@ -16,7 +16,7 @@
 
  Versions
  1.00aA  25 Nov 02 SWS  Created
- 1.00aB  11 Ded 06 SWS  Added Licence 
+ 1.00aB  11 Ded 06 SWS  Added License 
 
 ********************************************************************************/
 #ifndef __CHiTimer_h__
diff --git a/README.md b/README.md
@@ -1,25 +1,42 @@
-# BACnet Server MSTP Example CPP
+# BACnet Server MSTP Example C++
 
-A minumal BACnet MSTP server example written with C++ using the [CAS BACnet Stack](https://www.bacnetstack.com/). For a full featured BACnet Server example see the [BACnet Server Example CPP](https://github.com/chipkin/BACnetServerExampleCPP) project.
+A minimal BACnet MSTP server example written in C++ using the [CAS BACnet Stack](https://store.chipkin.com/services/stacks/bacnet-stack). For a full featured BACnet Server example see the [BACnet Server Example CPP](https://github.com/chipkin/BACnetServerExampleCPP) project.
 
-Device tree:
+## Releases
 
-- Device: 389999 (Device Rainbow)
-  - analog_value: 2 (AnalogValue Diamond)
+Build versions of this example can be downloaded from the [Releases](https://github.com/chipkin/BACnetServerMSTPExampleCPP/releases) page.
+
+## Installation
+
+Download the latest release zip file on the [Releases](https://github.com/chipkin/BACnetServerMSTPExampleCPP/releases) page.
 
-## Cli
+## Usage
 
-The serial port, baud rate, and MAC address of this BACnet MSTP server can be configured using command line parameters.
+The serial port, baud rate, and MAC address of this BACnet MSTP server can be configured using command line parameters:
 
 ```bash
 BACnetServerMSTPExampleCPP [serial port] [baud rate] [mac address]
 BACnetServerMSTPExampleCPP COM5 9600 1
 BACnetServerMSTPExampleCPP ttyS6 19200 25
 ```
 
-## Output
+Device tree:
+
+- Device: 389999 (Device Rainbow)
+  - analog_value: 2 (AnalogValue Diamond)
+
+## Build
+
+A [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) project is included with this project. This project also auto built using [Gitlab CI](https://docs.gitlab.com/ee/ci/) on every commit.
 
-The application outputs all BYTES sent or recived. BYTES with underscore after them are recived bytes. BYTES with a space after them are sent bytes. When the user presses the "enter" key, the MSTP stats, states, and events are printed for reference.
+1. Copy *CASBACnetStack_x64_Debug.dll*, *CASBACnetStack_x64_Debug.lib*, *CASBACnetStack_x64_Release.dll*, and *CASBACnetStack_x64_Release.lib* from the [CAS BACnet Stack](https://store.chipkin.com/services/stacks/bacnet-stack) project into the /bin/ folder.
+2. Use [Visual Studio 2019](https://visualstudio.microsoft.com/vs/) to build the project. The solution can be found in the */BACnetServerMSTPExample/* folder.
+
+A makefile that uses gcc is included for making executables on linux.
+
+## Example Output
+
+The application outputs all BYTES sent or received. BYTES with underscore after them are received bytes. BYTES with a space after them are sent bytes. When the user presses the "enter" key, the MSTP stats, states, and events are printed for reference.
 
 ```txt
 CAS BACnet Stack Server MSTP Example v0.0.1.0
@@ -86,16 +103,4 @@ MSTP Events:
       NextStationUnknown:    1ReceivedDataNeedingReply:    1    ReceivedInvalidFrame:    0
              ReceivedPFM:    1      ReceivedReplyToPFM:    1     ResetMaintenancePFM:    2
           RetrySendToken:    0         SendCustomFrame:    1      SendMaintenancePFM:    1
-```
-
-## Building
-
-A [Visual studio 2019](https://visualstudio.microsoft.com/downloads/) project is included with this project. This project also auto built using [Gitlab CI](https://docs.gitlab.com/ee/ci/) on every commit.
-
-A makefile that uses gcc is included for making excultables on linux.
-
-## Releases
-
-Build versions of this example can be downloaded from the releases page:
-
-[https://github.com/chipkin/BACnetServerMSTPExampleCPP/releases](https://github.com/chipkin/BACnetServerMSTPExampleCPP/releases)
+```
