Introduction

OpenMRN is a networking stack specifically designed for use in model model railroading. The initial goal is to provide support for the NMRAnet (http://www.nmranet.org) family of protocols which are based off of the OpenLCB (http://www.openlcb.org) family of protocols. NMRAnet protocols are designed to be agnostic of the physical medium over which messages travel. The OpenMRN provides support for multiple physical medium, such as CAN, while abstracting physical medium specific details from the application layers.

Getting Started Guide

See the Getting Started Guide for instructions on setting up the tools and running the example applications.

User API

See the User API page for direction on how an application can use the stack.

Copyright Licenses

A description of open source licenses can be found on the Open Source Initiative web site (http://opensource.org/licenses/index.html).

OpenMRN License

All of the OpenMRN source uses the BSD 2-clause license:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

FreeRTOS License

OpenMRN provides support for FreeRTOS. Other than FreeRTOSConfig.h, no FreeRTOS source code is directly bundled with OpenMRN. The build system knows how to find a separately distributed FreeRTOS distribution for building FreeRTOS libraries. Free RTOS uses a modified GPL license, the full text of which is provided at http://www.freertos.org/license.txt. It is possible to use FreeRTOS in a commercial product without having to release the source of bundled application code. The maintainers and copyright holders of OpenMRN are not liable for misuse of the FreeRTOS license.

Newlib License

OpenMRN uses Newlib (http://sourceware.org/newlib/) as a standard C library for some target and OS combinations. Newlib is a conglomeration of library parts all under free software licenses (http://sourceware.org/newlib/info.html). Newlib can be used in a commercial product without having to release the source of bundled application code. The maintainers and copyright holders of OpenMRN are not liable for misuse of the Newlib license.

cJSON License

OpenMRN provides a distribution of the cJSON JSON parser. The maintainers and copyright holders of OpenMRN are not liable for misuse of the cJSON license:

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.

TinyXML-2 Licence

OpenMRN provides a distribution of the TinyXML-2 XML parser. The maintainers and copyright holders of OpenMRN are not liable for misuse of the TinyXML-2 license. TinyXML-2 uses the zlib license:

TinyXML-2 is released under the zlib license:

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
This notice may not be removed or altered from any source distribution.

sys/tree.h License

OpenMRN provides a version of sys/tree.h from the FreeBSD/OpenBSD/NetBSD family of operating systems. The maintainers and copyright holders of OpenMRN are not liable for misuse of the sys/tree.h license. sys/tree.h uses the BSD 2-clause license:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR `‘AS IS’' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Microchip drivers license

OpenMRN includes certain generated code from Microchip Technology Inc to interface with their drivers for their PIC32MX microcontrollers.

Copyright (c) 2013-2015 released Microchip Technology Inc. All rights reserved. Microchip licenses to you the right to use, modify, copy and distribute Software only when embedded on a Microchip microcontroller or digital signal controller that is integrated into your product or third party product (pursuant to the sublicense terms in the accompanying license agreement). You should refer to the license agreement accompanying this Software for additional information regarding your rights and obligations.

SOFTWARE AND DOCUMENTATION ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS.

Created with MPLAB Harmony Version 2.06

Microchip licenses to you the right to use, modify, copy and distribute Software only when embedded on a Microchip microcontroller or digital signal controller that is integrated into your product or third party product (pursuant to the sublicense terms in the accompanying license agreement).

You should refer to the license agreement accompanying this Software for additional information regarding your rights and obligations.

SOFTWARE AND DOCUMENTATION ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS.

Layering Model

The OpenMRN software is broken down into distinct layers of. The lowest layer is acutely aware of the physical medium and the individual frames of data that pass over it. As one moves up in the layers, the constructs become more abstract and more object oriented.

Threading Model

An OpenMRN application always contains a minimum of one thread of execution managed by an operating system. In the case of FreeRTOS, an OpenMRN application will also contain an Idle Thread and a Timer Thread. OpenMRN is designed to support a number of different operating systems, and a thin abstraction is provided in order to hide any OS specific differences. The OS abstraction is provided by OS.hxx, and applications are encouraged to make use of when accessing OS features such as threads, mutexes, semaphores, etc...

Main Thread

The main thread is the thread of execution that os_main() is called with, os_main() being the entry point of an application. This thread is used for the application to initialize the stack. Typically, once any onetime initialization is complete, the OpenLCB stack inherits the main thread for its own use with a SimpleCanStack::loop_executor() call.

Timer Thread

FreeRTOS internally creates a thread for handling timers and events. This thread is managed by the RTOS and used by the RTOS. It is not available for application use.

Idle Thread

Some of the OS ports, such as FreeRTOS utilize an idle thread hook. This hook is used as a diagnostic tool to check the high water mark or each thread's stack. This can aid the developer in choosing the right stack size for each thread as to not overflow their stack and minimize total RAM usage.

Additional Threads

An application may instantiate additional threads of its own using the threading API found in OS.hxx.

Executors, Services, State Flows and Dispatch Flows

OpenMRN contains a further abstraction of the threading model, which is used by the OpenLCB stack. It is also available for application use and is described on the Executors, Services, State Flows, and Dispatch Flows page.

Hubs, Routers, and Gateways

OpenMRN is designed to implement Hubs, Routers, and Gateways that can be used to logically connect separate physical communications interfaces. More details can be found on the Hubs, Routers, and Gateways page.

Coding Guidelines

OpenMRN source code adheres to very strict coding guidelines. The guidelines can be found in the Coding Guidelines.

Table of Contents