integrated comms code

CONTRIBUTE.md

@@ -0,0 +1,66 @@
+# How to publish your work in an ABS repository
+Despite the ABS GitHub repositories being open to the community, they are internally managed and are subject to reviews. The review process prevents the master repo from containing wrong, incomplete or inconsistent code (or designs), and is oriented to provide detailed feedback on your proposed implementations. The ABS repositories are peer-reviewed by [M. Marí](mailto:marc.mari.barcelo@est.fib.upc.edu) (*mark-mb*) and [C. Araguz](mailto:carles.araguz@upc.edu) (*carlesaraguz*), who will post their comments to you implementations through this GitHub web platform. The review process is decomposed into the following steps:
+
+ 1. You fork the ABS repo in which you will be working (Software, Hardware or ARTOS).
+ 2. Push your local commits to your forked repo.
+ 3. Include a **detailed** `README.md` file explaining how to open/compile/test your files. Remember to include references to other communities (e.g. other repo's) if you have used libraries or special assets. External assets such as libraries, should not be included in ABS repo's unless it is strictly necessary (see note below). 
+ 3. Issue a [*pull-request*](https://help.github.com/articles/using-pull-requests/).
+ 4. In your pull-request form, provide thorough details of your changes, design, important sections or aspects that you consider important during the review process (e.g. unimplemented sections, purposefully ignored warnings and their justification, hard-coded parts that you expect to modify later, etc.)
+ 5. The reviewers will read, compile and execute your code and provide feedback.
+ 6. Then: 
+     * If your pull-request is **accepted** but requires some changes, you should provide them in the form of a new pull-request (step 4). The master repository will include your previous commits.
+     * If your pull-request is **rejected**, you need to fix your issues as soon as possible and generate a new pull-request (step 4). Remember that if this happened after the FDR, your course mark may rely on this second/fixed pull-request. 
+
+#### General recommendations
+* Start working on your local repository from the beginning. Using a GIT repository not only will allow you to recover previous versions or keep your developments well organised but will also allow you to issue several pull-requests during the course (and have them reviewed before the FDR).
+* Coordinate your efforts with the rest of collaborators so that you work in the appropriate folder from the beginning. Remember that the repository structure and file naming is also managed and has to be agreed with the rest of team members.
+* Read the repository's rules ***carefully*** (e.g. *CODING_STYLES.md*) before issuing your pull-requests.
+
+#### A note about external libraries or assets
+You may include external code or designs (e.g. libraries) if:
+
+* The external assets comply to the repository rules (i.e. no binaries, well documented, open-source, etc.)
+* You have performed some modifications to those assets or you are using modified versions that can't be get from official sources.
+* You always give credit to the original author(s) / source(s).
+* You justify your decision.
+
+#### General rules for the ABS software repository (*abs-software*)
+These repositories shall only include software-related development such as: software architecture modules, Arduino firmware, microcontroller's firmware. The repo **must never include**:
+
+* Project files (i.e. the kind of garbage left by programming IDE's such as NetBeans, Eclipse or MPLAB)
+* Autogenerated Makefiles that can only be executed by the programming IDE.
+* Binaries or built sources.
+* Programs that are not compliant with the coding styles (exception: code that you have not written, such as external libraries or headers).
+
+#### General rules for the ABS hardware repository (*abs-hardware*)
+Given that most PCB design frameworks don't usually generate text files, hardware designs must be kept in different folders according to their version. For PCB designs, the following (minimum) files have to be included:
+
+* The schematic (e.g. *".SchDoc"*)
+* The PCB layout (e.g. *".PcbDoc"*)
+* A PDF file with the schematic (organised in several pages, if needed) and layout (in a way that all layers can be seen, e.g. each layer in a different page).
+* The fabrication files (layers in Gerber format), as they would be sent to the manufacturer company.
+* A bill-of-materials Excel (or LibreOffice / Google Docs spreadsheet) with, at least, the following columns: 
+    * The component description and *value* (e.g. "Resistor 1k2", "RF transmitter", "Inductor 23 mH"); 
+    * the component name(s) as shown in schematics and silk-screen layer (e.g. IC23, C34, R2, L1); 
+    * the manufacturer's reference (e.g. LT3129);
+    * the footprint/case reference;
+    * the purchasing reference (e.g. Farnell product ID) and a descriptive comment;
+    * and the quantity.
+* A `README.md` file with stating:
+    * The **version number** and name of the software that has been used to generate the files (e.g. "Altium Designer v15.43.2")
+    * Special fabrication requirements, if any (e.g. FR4 substrate).
+
+May be included in the repository: footprint libraries for non-standard components, a `Datasheets` folder containing PDF component datasheets.
+
+##### Folder naming
+All PCB designs must be placed in folders applying the following naming rules:
+
+    UPCNSL-ABS-XXX-YYY-vN.NN
+
+Where:
+
+* `UPC-NSL-ABS` is the generic codename for ABS boards from the NanoSat Lab / UPC.
+* `XXX` is the subsystem: `ARDS` (for Arduino Space board), `EPS` (Electrical Power Subsystem boards, such as the PV panels), `POL` (for Point-of-Load boards), `COMMS` (for RF boards of the comms. subsystem).
+* `YYY` is a secondary nomenclature indicating the type of board (e.g. `TEST`, `PLATFORM`, `FLATSAT`...)
+* `vN.NN` is the version number (e.g. `v1.2`)
+* All files inside a PCB folder **must** be prefixed with the folder name.

src/Arduino/abs/README_comms.md

@@ -0,0 +1,24 @@
+# COMMS DRIVER
+
+## Definition
+
+In the comms driver it has been implemented all the functionalities for the AX5042 transceiver. The required algorithms for the transmission and reception routines are implemented in files hdlc.c and comms.cpp. These contain Main functions (configure, change_x, transmit and receive) . The final SPI connection between the arduino board and the 
+transceiver is also defined here through the functions write_register and read_register.
+
+The main code in the comms driver is structured as a class using c++. If using the Arduino IDE, the driver must be imported following the procedure for its IDE.
+
+## Modifications from the previous version
+1. Fix errors from the previous version.
+2. Addition of one configuration function for each register.
+3. Restructuring of the configuration code using functions mentioned in the previous statement.
+4. Analysis of the dependencies between registers in order to implement change_x function. Implementation of change_x function.
+5. Change the reception algorithm to make an error control and send back to the HWmod all the packet.
+6. Integration of the new comms driver version in the Arduino firmware.
+7. Creation of new _structs_ and _enums_ in the Arduino firmware.
+8. Develop comms_test to test the execution time of configuration and change_x routines.
+
+
+## Future modifications (expected in a few weeks)
+1. Implementation of a reception event in order to update the reception info every some time and avoid stopping Arduino from its main routine.
+    - Option B. Using interruptions from the transceiver (FIFO full, FIFO empty...).
+2. Adaptation of communication protocol with HWmod.