This is the main repository of the Open Source John O.S. Project.
- Current version: 2.2.3
- Downloads: com.robypomper.josp / downloads @ Bitbucket
- Repository: com.robypomper.josp / master @ Bitbucket
- Libraries: Group Id com.robypomper.josp @ Maven Central
- User manuals:
Makers,
Developers
and 
End Users - References: JOSP Components
The John O.S. Project simplify the design and the build process of a modern Internet of Things solutions.
The major benefits offered by this project when creating IoT solutions based on
the JOSP Eco-System are:
- reduces smart object's creation into a 5 minutes activity, even without coding skills
- it's possible integrate any kind of connected object, regardless of communication protocol used by the object
- develop customized software that easily interact with objects
- startups local and cloud connections between service and objects out-of-the-box
- provides communication security and object's access control by design also when not provided natively
- it is completely Open Source
The Public John Cloud Platform instance is reachable here.
Note: These docs are intended for JOSP developers.
Other users like
Makers,
Developers
and End Users
can look at the
JOSP user manuals.
Thanks to the simple and flexible design of the JOSP Eco-System, became possible setup any kind of IoT solution. The components that compose a JOSP Eco-System are highly scalable and can be adapted to almost any needs. For example a simple, local solution can use only a local communication (LAN, P2P...) so it do not require the cloud component. On other examples there can be many objects and only one UI the control them all; other solutions may involve different end users that require different UIs (mobile/desktop, user/maintainer, supervisor/data collection, brand A/brand B...).
Like any other IoT Eco-System, a JOSP Eco-System allows different software on different machines communicate together. Direct Communication, if they can communicate via a local LAN; or Cloud Communication, if they can both reach the cloud platform. In to the JOSP project define those components are defined as following:
-
the John Object Daemon is the object's agent that represent one or more physical objects. This agent can be run on embedded system (as Native JOSP Object) or on local servers (as JOSP Object Hub). It can be also run in a cloud service to create CloudToCloud integrations (as JOSP Web Object). Among JOD's main tasks, there are that of sharing the capabilities of the object on the network, but also managing connections and access control to the object.
-
a JOSP Services is any software that include the John Service Library and then is able to monitor and/or control objects remotely. Software like mobile and desktop apps can be used as UI to manage objects, cloud services can collect data from objects and process them with Data Analytics and other AI software.
-
and (only if required) the John Cloud Platform that act as a bridge between objects and services instances. The JCP service can handle all Object to Service communications via the public internet in a secure and transparent manner for the end user. Moreover, it provides also a Web FrontEnd to manage objects, users and the cloud itself; a JSL Web Bridge implementation (used by web apps like the Web FrontEnd); and finally a set of APIs used to coordinate all JOSP Eco-System's components. All those services can be run as a single SpingBoot application via the JCP All implementation.
All software, tools and services provided by the JOSP Project are designed around IoT's actors. The complexity behind the IoT does not derive only from the multitude of technologies used, but also from the growing number of people who work, manage, use and ultimately maintain an IoT solution.
It doesn't matter whether the hardware or the software is created first. Simply
decide whether to be a
Maker or a
Developer. Then follow the guidelines to
develop your Object/Service as its best. Makers will know how to share object's
capabilities to the Eco-System and make them 'attractive' for service's Developers.
On the other side, Developers will learn how to identify connected Objects to
interact with, not only by name/model but also by capabilities and other details
to best suit service's purposes.
Then, at the center of any Eco-System, there is the
End User. In this group are included all peoples who 'use' the object,
both directly (physical interactions) and connectedly (digital interactions).
The main example is the owner of a smart lamp: he can switch on/off the lamp
directly via a physical switch, but he can also control the lamp through a
mobile app. Another case is about the maintainer, for example a plumber as boiler
maintainer can use his tablet to connect to the boiler and get a complete
diagnosis of it.
In the latest case, the plumber can be part of the same company that manufactured the boiler, as Customer Service operator. That company, started as boiler's Maker, and after selling it, the company itself becomes a boiler's End User, with the permission of the boiler owner. That means the roles are variable and any Maker/Developer can follow and support hid products/services alog all their life-cycles.
JOSP's developers can find more info about the JOSP Project Docs and his development in those pages. For a rapid JOSP Eco-System startup, please read next chapter.
To start working with JOSP project you must clone this repository via Git then, with the included Gradle Wrapper you can execute project's tasks to build and run your own IoT Eco-System directly from those sources. That require Git and Java JDK installed on your pc. And, if you would also execute the JCP Cloud platform, then Docker and docker-compose are also required.
Note: These getting started is intended for JOSP developers. Other users like
Makers,
Developers
and End Users
can look at the JOSP Project's User manuals
getting started.
- Install development tools required to download, build and run the JOSP Project:
- Install Git
- install Java JDK
- and install Docker and docker-compose (Optional to run JCP Cloud)
- Clone the com.robypomper.josp repository from BitBucket
repository
$ git clone https://bitbucket.org/johnosproject_shared/com.robypomper.josp.git
- Enter cloned directory and start executing Gradle tasks via wrapper
$ cd com.robypomper.josp $ ./gradlew --console=plain {TASK_NAME}
Now you are ready to build and run your own IoT Eco-System. Depending on your
needs you can configure and start up a local/cloud JOSP Eco-System. You can also
implement your JOSP service or make your JOSP Object directly from the JOSP
Project source code, but we suggest following the Makers
and Developers
manuals to make your products/services updatable and easily maintainable.
The first, basic IoT Eco-System is composed only by a connected object, and by a service to interact with. To run a basic IoT Eco-System it's required to run the JOD object agent, and the shell version of the JSL library.
The only requirement is that both instance have to be connected to the same local network.
- Run the John Object Daemon (JOD)
$ ./gradlew javaJODRun
- Run the John Service Library Shell (JSL Shell)
$ ./gradlew javaJSLRun
That's it! Your local IoT EcoSystem is running!
Communication initialization
When executed, the JOD agent starts and publish a local server. At the same time, when initialized, the JSL library starts discovery local object. When the JSL library discover an object on the local network, it starts the Direct Communication (Srv2Obj); after the SSL handshaking, the JOD agent (base on object's permission) send his presentation messages to the service. At this point, if the JSL service has the right permissions, can send action command and will receive all statuses updates to/from JOD agent. Remember that, for security reasons, the object's presentation messages are sent only to JSL service according to object's access permissions.
Interactive shells
Once you executed both tasks on the same machine, the JSL Shell can starts
interact with the JOD Agent. Both software, the JOD and JSL Shell, provides a
shell to interact with them. Type ?list to print shell's command list or check
out the JOD Shell and
JSL Shell commands list reference.
To stop the JOD agent or the JSL Shell, type the exit command to the
corresponding shell or kill them via their PID.
Gradle tasks
Gradle's javaJODRun task run a full working instance of the JOD agent
that represent a development object, you can customize this object's structure
using example structures like struct_LINUX.jod
or struct_MAC.jod
or struct_WIN.jod files. This task once
executed for the first time, it loads always the same JOD Object from envs/runnubles/jod/JOD
dir. For other execution options see the JOD Runners
tasks group.
Gradle's javaJSLRun task run a shell application that implement a basic
JSL service. This JSL service translate all JSL features in
interactive commands. Like for
javaJODRun task, the javaJSLRun task generate his configs on first
execution and then stored them into the envs/runnables/jsl/JSL dir.
Other execution options are available at JSL Runners
tasks group.
You can run first the JOD agent and second the JSL Shell or vice versa. Both
JOSP components print log messages on the console and save them on files in
their logs sub-dir. So to run multiple instances of JOD and/or JSL you
must run them in different terminals.
JOD objects and JSL services can communicate directly when they are on the same local network, or remotely via the JOSP Cloud Platform. The JCP is composed by 4 micro-services plus a DBMS and an Auth services:
- JCP DBMS: manage the DBs (jcp_auth, jcp_apis...) for other micro-services
- JCP Auth: provide the authentication and authorization service
- JCP All:
The monolithic JCP Service that include all the following:
- JCP APIs: basic JCP APIs required by JOSP objects and services
- JOSP Gateways: the cloud gateways that acts as bridge between JOSP objects and services
- JOSP JSL Web Bridge: the JSL's HTTP APIs manager for JSL services as web clients
- JOSP Front End: the JCP front end
When an IoT Eco-System requires cloud connectivity, objects and services with the Cloud Communication enabled can communicate together via the John Cloud Platform that acts as a bridge. When a JSL service connect to the JCP Gateways, it receives the object's presentations messages. So, the JSL service know all available objects (via cloud). At the same time, when it's a JOD agent that connects to JCP Gateways, it sends his presentation to the JCP Gateways, that's forwarded to the connected JSL services. Object's presentation are sent only to JSL service according to object's access permissions.
To startup and shutdown all JCP micro-services once, run one of following
Gradle's tasks: jospCloud_Start or jospCloud_Stop. When are running
you can print JCP microservice's logs with following command:
$ ./gradlew jospCloud_Start
$ tail -f tail -f envs/runnables/jcp/{JCP_SERVICE}_StartAsync/jcp.log_{START_DATE_TIME}
Ctrl+CTo reduce time wast during microservice restart, micro-services are parted in two groups: Docker and Soft. Each group can be started and stopped independently to the other one. Be careful to start up the Soft' micro-services only when all Docker's micro-services are running. There are also tasks for startup and shutdown each microservice individually.
When the John Cloud Platform is running, you can start JOD and JSL instances
with their javaJODRun and javaJSLRun tasks. Previous tasks start
JOD and JSL instances using their default configs
(jod.yml and
jsl.yml) that enable by default Local
and Cloud communications on both components.
Once started, both JOD and JSL can be connected/disconnected to the JCP Cloud and local communication started/stopped with corresponding shell commands (JOD Shell's cmds and JSL Shell's cmds).
To run the JOD and JSL components with different communication configs you can use the tasks from JOD Runners Alternative and JSL Runners Alternative.
Combining this tasks, allow you to simulate different architectures for different IoT Solutions.
Any kind of collaboration is welcome! This is an Open Source project, so we are happy to share our experience with other developers, makers and users. Bug reporting, extension development, documentation and guides etc... are activities where anybody can help to improve this project.
One of the John O.S. Project’s goals is to release more John Objects Utils & Apps to allow connecting even more connected objects from other standards and protocols. Checkout the Utils & Apps extensions list and start collaborating with a development team or create your own extension.
At the same time we are always looking for new use cases and demos. So, whether you have just an idea or are already implementing your IoT solution, don't hesitate to contact us. We will be happy to discuss with you about technical decisions and help build your solution with John’s component.
Please email to tech@johnosproject.com.
John Operating System Project provided software must communicate together and with 3rd party software. To do that they use different protocols or interfaces. Depending on the protocol or interface supported versions a software can/cannot communicate with others. Here the protocols and interfaces versions supported by this release. That means each software build from current source code's release can communicate with software that also support one of following versions.
| Protocol / Interface | Supported Versions |
|---|---|
| JOSP Protocol | 2.0 |
| JCP APIs Ver | 2.0 |
| JSL APIs Ver | 1.0 |
| JOD Executors | 2a |
| JOD Structure | 2a |
| JSL Interface | 2.2.0 |
All components from current source code's release are build with 2.2.3 version.
Older version of JOSP source code:
JOSP Project's provide different software (JOSP Components) and each one of them have the corresponding licence. In the following table the list of JOSP Components and their licences.
| Component | Licence |
|---|---|
| JOSP JOD | [GPLv3](LICENSES/John Object Daemon) |
| JOSP JSL | [Apache Licence 2.0](LICENSES/John Service Library) |
| JCP All | [AGPLv3](LICENSES/John Cloud Platform) |
| JCP APIs | [AGPLv3](LICENSES/John Cloud Platform) |
| JCP Gateways | [AGPLv3](LICENSES/John Cloud Platform) |
| JCP JSL Web Bridge | [AGPLv3](LICENSES/John Cloud Platform) |
| JCP Gateways | [AGPLv3](LICENSES/John Cloud Platform) |
| JCP Front End | [AGPLv3](LICENSES/John Cloud Platform) |
This project use different Open Source software, click here for the JOSP dependencies list and their licences.