upm  1.5.0
Sensor/Actuator repository for libmraa (v1.8.0)
Contributing a module

Here are the rules of contribution:

Including the MIT license

Choosing the MIT license is preferred for the UPM repository. Below is the comment block needed at the top each source file:

    /*
     * The MIT License (MIT)
     *
     * Author: <your full name> 
     * Copyright (c) <year> <copyright holder>
     *
     * Author: <contributing author full name - if applicable> 
     * Copyright (c) <year> <copyright holder>
     *
     * Permission is hereby granted, free of charge, to any person obtaining a copy of
     * this software and associated documentation files (the "Software"), to deal in
     * the Software without restriction, including without limitation the rights to
     * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
     * the Software, and to permit persons to whom the Software is furnished to do so,
     * subject to the following conditions:
     *
     * The above copyright notice and this permission notice shall be included in all
     * copies or substantial portions of the Software.
     *
     * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
     * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
     * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
     * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
     * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
     * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
     */

Code signing

The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below:

    Developer's Certificate of Origin 1.1

    By making a contribution to this project, I certify that:

    (a) The contribution was created in whole or in part by me and I
        have the right to submit it under the open source license
        indicated in the file; or

    (b) The contribution is based upon previous work that, to the best
        of my knowledge, is covered under an appropriate open source
        license and I have the right under that license to submit that
        work with modifications, whether created in whole or in part
        by me, under the same open source license (unless I am
        permitted to submit under a different license), as indicated
        in the file; or

    (c) The contribution was provided directly to me by some other
        person who certified (a), (b) or (c) and I have not modified
        it.

    (d) I understand and agree that this project and the contribution
        are public and that a record of the contribution (including all
        personal information I submit with it, including my sign-off) is
        maintained indefinitely and may be redistributed consistent with
        this project or the open source license(s) involved.

then you just add a line to each of your commits with --signoff saying

    Signed-off-by: Random J Developer <random@developer.example.org>

using your real name (sorry, no pseudonyms or anonymous contributions.) Unsigned commits will not be accepted.

Creating a new sensor library using the sensortemplate

A stubbed-out sensor library is available which can be leveraged to get up-and-running quickly when writing a new sensor library. Use the shell commands below to generate collateral files for your new sensor library.

1 #!/bin/bash
2 
3 function make_new_sensor {
4  export SensorName=$1
5  # Get a lowercase version of the string
6  export sensorname=${SensorName,,}
7 
8  # Make sure this is run from the root UPM directory
9  if ! grep -q 'UPM ' README.md; then echo "Please run from the root UPM directory"; return -1; fi
10 
11  printf "Generating new sensor: ${SensorName}\n"
12  # Copy sensortemplate files to ${sensorname}
13  find docs/ examples/ src/ -name '*sensortemplate*' -exec bash -c 'cp -r $0 ${0/sensortemplate/${sensorname}}' {} \;
14  # Copy SensorTemplate files to ${SensorName}
15  find examples/ src/ -name '*SensorTemplate*' -exec bash -c 'cp -r $0 ${0/SensorTemplate/${SensorName}}' {} \;
16  # Rename sernsortemplate src files
17  rename "s/sensortemplate/${sensorname}/" src/${sensorname}/*
18  # Search/replace the new files, replacing all instances of sensortemplate
19  perl -p -i -e "s/SensorTemplate/${SensorName}/g" src/${sensorname}/* examples/*/*${sensorname}* examples/*/*${SensorName}*
20  perl -p -i -e "s/sensortemplate/${sensorname}/g" src/${sensorname}/* examples/*/*${sensorname}* examples/*/*${SensorName}*
21  # Remove objects starting with "//" from the new library descriptor .json file
22  perl -p -i -e 'BEGIN{undef $/;} s/\s+"\/\/.*?},//smg' src/${sensorname}/${sensorname}.json
23  # Add mynewmodule example target for java
24  perl -p -i -e "s/^((.*)SensorTemplateSample sensortemplate(.*))/\1\n\2${SensorName}Sample ${sensorname}\3/g" examples/java/CMakeLists.txt
25  # Add mynewmodule example mappings for doxygen
26  perl -p -i -e "s/^(.*SensorTemplateSample.*)$/\1\n${sensorname}.cxx\t${SensorName}Sample.java\t${sensorname}.js\t${sensorname}.py/g" doxy/samples.mapping.txt
27  # Display TODO's
28  printf "Generation complete for sensor library: ${SensorName}\n"
29  printf "TODO's:\n"
30  printf "\t1. Update src/hdr files: src/${sensorname}/${sensorname}.hpp src/${sensorname}/${sensorname}.cxx\n"
31  printf "\t\tChange the Author\n"
32  printf "\t\tChange the Copyright\n"
33  printf "\t\tUpdate all doxygen tags (follow directions for @tags)\n"
34  printf "\t2. Update examples: examples/*/${sensorname}.* examples/java/*${SensorName}*.java\n"
35  printf "\t3. Overwrite docs/images/${sensorname}.png with a valid image of your sensor\n"
36 }
37 
38 # Call make_new_sensor with your new sensor name, example: 'MyNewSensor1234'
39 make_new_sensor MyNewSensor1234

Once all files have been created, they can be used as a starting-point for your new library. They will need additional customization (your name/email address, documentation, sensor images, etc).