Added support for MK20DX128 and MK20DX256. Updated documentation and …

…made an example.
dannysilence · May 12, 2020 · de5a73b · de5a73b
1 parent 6eaf740
commit de5a73b
Show file tree

Hide file tree

Showing 8 changed files with 275 additions and 10 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,5 @@
+# Changelog
+
+## v1.0.0
+
+- Initial commit
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -18,7 +18,6 @@ if (DEFINED MCU)
 	FetchContent_Declare(
 		core
 		GIT_REPOSITORY 	[email protected]:bolderflight/software/core.git
-		GIT_TAG					v0.8.0
 	)
 	FetchContent_MakeAvailable(core)
 	# Add the library target
@@ -37,4 +36,23 @@ if (DEFINED MCU)
 		$<INSTALL_INTERFACE:include>
 	)
 endif()
-
+# Example and test if this project is built separately
+if (PROJECT_NAME STREQUAL CMAKE_PROJECT_NAME)
+	if (DEFINED MCU)		
+		# Add the spi example target
+		add_executable(sbus_example examples/sbus_example.cc)
+		# Add the includes
+		target_include_directories(sbus_example PUBLIC 
+			$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+			$<INSTALL_INTERFACE:include>
+		)
+		# Link libraries to the example target
+		target_link_libraries(sbus_example
+			PRIVATE 
+				sbus
+		)
+		# Add hex and upload targets
+		include(${CMAKE_SOURCE_DIR}/cmake/flash_mcu.cmake)
+		FlashMcu(sbus_example ${MCU})
+	endif()
+endif()
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,76 @@
+# Bolder Flight Systems Contributing Guide
+The following guidelines set best practices for contributing to Bolder Flight Systems software repositories.
+
+## Steps
+Software development and contribution should follow these steps:
+   * Develop
+   * Test 
+   * Document 
+   * Merge
+   * Tag
+
+Further detail is provided below for each step.
+
+### Develop
+All development should occur on a separate branch from master. Software should be developed following our [Style Guide](#style). 
+
+#### Style Guide<a name="style"></a>
+Follow the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html). Any parameter or variable names, which contain unit specific data should be appended with an underscore and the units (i.e. accel_z_mss). Several common units are listed below; as a general rule SI units should be used.
+   * _c: Celsius
+   * _pa: Pascal
+   * _m: meter
+   * _rad: radian
+   * _ut: micro-tesla
+   * _s: seconds
+   * _ms: milliseconds
+   * _us: microseconds
+   * _ms: meters/second
+   * _rads: radians/s
+   * _mss: meters/second/second
+
+Prefer to use _float_ instead of _double_ unless there is a specific need for improved accuracy. Specify integer size in all cases where a certain number of bytes are expected (i.e. uint16_t where 2 bytes is assumed); otherwise use unsigned or signed int. Typically, we are not concerned with program size and unsigned or signed int work well for integers and index values. If a certain number of bytes are needed they need to be called out directly since different compilers and platforms can change the number of bytes stored in a short, for instance.
+
+#### External sources licensing
+If you use external sources, ensure they are licensed MIT, BSD, or a similarly permissive license. We would like to limit the amount of LGPL code in our code base and need to avoid all GPL and unlicensed code.
+
+If you are using external sources with licenses other than MIT or BSD, contact [Brian](mailto:[email protected]) to discuss options.
+
+#### Examples
+Develop examples demonstrating your code's functionality and include expected outputs in comments. These examples provide an easy access point to learning your code and ensuring that it installed correctly.
+
+### Tests
+All tests should pass before a pull request is issued. At a minimum, the following tests should be run:
+   * Linting
+   * Build
+   * Test
+      * Inputs
+      * Expected values
+
+Tests are run using the [Google Test framework](https://github.com/google/googletest).
+#### Linting
+Linting tests check for conformance to the style guide - analyzing the code for potential errors and leading to better readibility. [cpplint](https://raw.githubusercontent.com/google/styleguide/gh-pages/cpplint/cpplint.py) should be used to conduct linting tests with verbosity level 0.
+
+#### Build
+Libraries, example code, and tests should be compiled with CMake without error. We typically use CMake with an AMD64 Linux target for general libraries. CMake should be [built from source](https://github.com/Kitware/CMake) and gcc compilers available on the target system. A [Docker](https://hub.docker.com/r/flybrianfly/gcc-cmake) is available to ease this process.
+
+Executables targetting embedded hardware should use the [core library](https://gitlab.com/bolderflight/software/core) as a dependency, which includes microprocessor startup code and CMake cross-compile toolchain instructions. The [GNU ARM Embedded Toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads) needs to be installed to build embedded software. Again, a [Docker](https://hub.docker.com/r/flybrianfly/gcc-cmake) is available to ease this process.
+
+#### Inputs
+Test all parameters against unexpected values, such as NULL inputs, buffer overflows, and zero or negative values. Try to capture all potential combinations of malformed inputs to ensure that your code is protecting against these. Assume that your fellow developers will not read your documentation and will try to use your code with incorrect parameters.
+
+#### Expected values
+Test against expected values to ensure that your software algorithms are computing outputs correctly.
+
+#### CI Pipeline
+Update the CI pipeline configuration in _.gitlab-ci.yml_ to incorporate all additional tests that you add. The _bfs_ tag should be used to specify using Bolder Flight Systems' runners, which are configured to compile and test our software.
+
+### Document
+Document all API changes in the repository README.md file. Specify what each function and method does, input parameters, and outputs. Give a short example of how to use that block of code. Ideally these example snippets will be pulled from the example executable.
+
+### Merge
+Pushing directly to the master branch is dangerous - it enables changes to be made without proper testing and review. This practice also increases the risk of pushing breaking changes and having inadequate documentation. You should create a branch, make your changes, run tests, update documentation, and submit a merge request for review and incorporation.
+
+The CHANGELOG.md will be updated to briefly document code changes.
+
+### Tag
+Tags are used to specify release version numbers in [semver](https://semver.org/) formatting. These tags are important because repositories using your code as a dependency will pull, build, and validate against a specific version, rather than continuously needing to manage code updates following HEAD.
diff --git a/LICENSE.md b/LICENSE.md
@@ -0,0 +1,2 @@
+# License
+This software is Bolder Flight Systems proprietary and trade secret. Restrict distribution to Bolder Flight Systems staff, partners with an appropriate NDA, or customers with an appropriate licensing agreement. If in doubt, check with [Brian](mailto:[email protected]) regarding distribution.
diff --git a/README.md b/README.md
@@ -1,3 +1,86 @@
 # sbus
+This library communicates with SBUS receivers and servos. 
+   * [License](LICENSE.md)
+   * [Changelog](CHANGELOG.md)
+   * [Contributing guide](CONTRIBUTING.md)
 
-SBUS encoder and decoder.
+# Description
+SBUS is a bus protocol for receivers to send commands to servos. Unlike PWM, SBUS uses a bus architecture where a single serial line can be connected with up to 16 servos with each receiving a unique command. SBUS capable servos are required; each can be programmed with a unique address using an SBUS servo programmer.
+
+SBUS can be used to receive pilot commands from an SBUS capable receiver to use as input to a flight control system. SBUS outputs can be sent to SBUS capable capable servos. Advantages compared to PWM include a reduction in vehicle wiring and ease of parsing SBUS packets.
+
+The SBUS protocol uses an inverted serial logic with a baud rate of 100000, 8 data bits, even parity, and 2 stop bits. The SBUS packet is 25 bytes long consisting of:
+   * Byte[0]: SBUS header, 0x0F
+   * Byte[1 -22]: 16 servo channels, 11 bits each
+   * Byte[23]
+      * Bit 5: frame lost (0x20)
+      * Bit 4: failsafe activated (0x10)
+   * Byte[24]: SBUS footer
+
+Note that lost frame is indicated when a frame is lost between the transmitter and receiver. Failsafe activation typically requires that several frames are lost in a row and indicates that the receiver has moved into failsafe mode. Packets are sent approximately every 10 ms. FrSky receivers will output a range of 172 - 1811 with channels set to a range of -100% to +100%. Using extended limits of -150% to +150% outputs a range of 0 to 2047, which is the maximum range acheivable with 11 bits of data.
+
+## Installation
+
+## Methods
+
+**Sbus(HardwareSerial &ast;bus)** Creates an Sbus object. A pointer to the Serial object corresponding to the serial port used is passed. The RX pin of the serial port will receive SBUS packets and the TX pin will send SBUS packets.
+
+```C++
+Sbus sbus(&Serial1);
+```
+
+**void Begin()** Initializes SBUS communication.
+
+```C++
+sbus.Begin();
+```
+
+**bool Read()** Parses SBUS packets, returns true on successfully receiving an SBUS packet.
+
+```C++
+if (sbus.Read()) {
+   // Do something with the received data
+}
+```
+
+**void Write()** Writes an SBUS packet. The packet is written immediately, you should regulate timing of sending packets to servos to maintain a frequency of approximately 100 Hz.
+
+```C++
+sbus.Write();
+```
+
+**std::array<uint16_t, 16> rx_channels()** Returns the array of received channel data.
+
+```C++
+std::array<uint16_t, 16> sbus_data = sbus.rx_channels();
+```
+
+**std::array<uint16_t, 16> tx_channels()** Returns the array of channel data to be transmitted.
+
+```C++
+std::array<uint16_t, 16> sbus_tx_data = sbus.tx_channels();
+```
+
+**void tx_channels(const std::array<uint16_t, 16> &val)** Sets the channel data to be transmitted.
+
+```C++
+sbus.tx_channels(sbus_tx_data);
+```
+
+**bool lost_frame()** Returns true if a frame has been lost.
+
+```C++
+bool lost_frame = sbus.lost_frame();
+```
+
+**bool failsafe()** Returns true if the receiver has entered failsafe mode.
+
+```C++
+bool failsafe = sbus.failsafe();
+```
+
+**void End()** Frees the serial port used by the Sbus object.
+
+```C++
+sbus.End();
+```
diff --git a/examples/sbus_example.cc b/examples/sbus_example.cc
@@ -0,0 +1,43 @@
+/*
+* Brian R Taylor
+* [email protected]
+* 
+* Copyright (c) 2020 Bolder Flight Systems
+*/
+
+#include "sbus/sbus.h"
+
+/* SBUS object */
+Sbus sbus(&Serial1);
+
+int main() {
+  /* Serial to display data */
+  Serial.begin(115200);
+  while(!Serial) {}
+  /* Begin communicating on SBUS serial */
+  sbus.Begin();
+  while(1) {
+    /* Check if SBUS packet received */
+    if (sbus.Read()) {
+      /* Grab the received SBUS data */
+      std::array<uint16_t, 16> sbus_data = sbus.rx_channels();
+      bool lost_frame = sbus.lost_frame();
+      bool failsafe = sbus.failsafe();
+      /* Print channel data */
+      for (unsigned int i = 0; i < 16; i++) {
+        Serial.print(sbus_data[i]);
+        Serial.print("\t");
+      }
+      /* Print lost frames and failsafe */
+      Serial.print(lost_frame);
+      Serial.print("\t");
+      Serial.println(failsafe);
+      /* Copy read SBUS data to transmit buffer */
+      sbus.tx_channels(sbus_data);
+      /* Write SBUS data to servos */
+      sbus.Write();
+    }
+  }
+}
+
+
diff --git a/include/sbus/sbus.h b/include/sbus/sbus.h
@@ -13,7 +13,7 @@
 
 class Sbus {
  public:
-  Sbus(HardwareSerial &bus);
+  explicit Sbus(HardwareSerial *bus);
   void Begin();
   bool Read();
   void Write();
@@ -23,6 +23,7 @@ class Sbus {
   bool failsafe();
   bool lost_frame();
   void End();
+
  private:
   /* Communication */
   HardwareSerial *bus_;
@@ -44,4 +45,4 @@ class Sbus {
   bool Parse();
 };
 
-#endif
+#endif  // INCLUDE_SBUS_SBUS_H_
diff --git a/src/sbus/sbus.cc b/src/sbus/sbus.cc
@@ -7,13 +7,37 @@
 
 #include "sbus/sbus.h"
 
-Sbus::Sbus(HardwareSerial &bus) {
-  bus_ = &bus;
+/* Needed for emulating two stop bytes on Teensy 3.0 and 3.1/3.2 */
+#if defined(__MK20DX128__) || defined(__MK20DX256__)
+namespace {
+  IntervalTimer serial_timer;
+  HardwareSerial *sbus_bus;
+  uint8_t sbus_packet[25];
+  volatile int send_index;
+  void SendByte() {
+    if (send_index < 25) {
+      sbus_bus->write(sbus_packet[send_index]);
+      send_index++;
+    } else {
+      serial_timer.end();
+      send_index = 0;
+    }
+  }
+}  // namespace
+#endif
+
+Sbus::Sbus(HardwareSerial *bus) {
+  bus_ = bus;
 }
 void Sbus::Begin() {
   parser_state_ = 0;
   previous_byte_ = SBUS_FOOTER_;
-  bus_->begin(BAUD_, SERIAL_8E2_RXINV_TXINV);
+  #if defined(__MK20DX128__) || defined(__MK20DX256__)
+    bus_->begin(BAUD_, SERIAL_8E1_RXINV_TXINV);
+    sbus_bus = bus_;
+  #else
+    bus_->begin(BAUD_, SERIAL_8E2_RXINV_TXINV);
+  #endif
 }
 bool Sbus::Read() {
   if (Parse()) {
@@ -25,7 +49,7 @@ bool Sbus::Read() {
     rx_channels_[4]  = (uint16_t) ((rx_buffer_[6]  >> 4  | rx_buffer_[7]  << 4)                         & 0x07FF);
     rx_channels_[5]  = (uint16_t) ((rx_buffer_[7]  >> 7  | rx_buffer_[8]  << 1  | rx_buffer_[9] << 9)   & 0x07FF);
     rx_channels_[6]  = (uint16_t) ((rx_buffer_[9]  >> 2  | rx_buffer_[10] << 6)                         & 0x07FF);
-    rx_channels_[7]  = (uint16_t) ((rx_buffer_[10]  >> 5 | rx_buffer_[11] << 3)                         & 0x07FF);
+    rx_channels_[7]  = (uint16_t) ((rx_buffer_[10] >> 5  | rx_buffer_[11] << 3)                         & 0x07FF);
     rx_channels_[8]  = (uint16_t) ((rx_buffer_[12]       | rx_buffer_[13] << 8)                         & 0x07FF);
     rx_channels_[9]  = (uint16_t) ((rx_buffer_[13] >> 3  | rx_buffer_[14] << 5)                         & 0x07FF);
     rx_channels_[10] = (uint16_t) ((rx_buffer_[14] >> 6  | rx_buffer_[15] << 2  | rx_buffer_[16] << 10) & 0x07FF);
@@ -69,7 +93,20 @@ void Sbus::Write() {
   tx_buffer_[22] =  (uint8_t) ((tx_channels_[15]  & 0x07FF) >> 3);
   tx_buffer_[23] = 0x00;
   tx_buffer_[24] = SBUS_FOOTER_;
-  bus_->write(tx_buffer_, sizeof(tx_buffer_));
+
+  #if defined(__MK20DX128__) || defined(__MK20DX256__)
+    /* 
+    * Use ISR to send byte at a time,
+    * 130 us between bytes to emulate 2 stop bits
+    */
+    __disable_irq();
+    memcpy(sbus_packet, tx_buffer_, sizeof(sbus_packet));
+    __enable_irq();
+    serial_timer.priority(255);
+    serial_timer.begin(SendByte, 130);
+  #else
+    bus_->write(tx_buffer_, sizeof(tx_buffer_));
+  #endif
 }
 std::array<uint16_t, 16> Sbus::rx_channels() {
   return rx_channels_;
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# License
		This software is Bolder Flight Systems proprietary and trade secret. Restrict distribution to Bolder Flight Systems staff, partners with an appropriate NDA, or customers with an appropriate licensing agreement. If in doubt, check with [Brian](mailto:[email protected]) regarding distribution.