isabella232 / simplesensor

A Python IoT framework to simplify sensor integration

SimpleSensor - DOCS WIP

A modular and threaded Python IoT framework to easily integrate sensors into your projects.

Table of Contents

• About
  • Modules
    • Collection modules
    • Communication modules
  • Logger
• Setup
• Documentation
  • 1. Shared
    • 1.1. Message
    • 1.2. ModuleProcess
    • 1.3. ThreadsafeLogger
  • Contributed modules
• Contributing
  • Issues
  • Pull requests
  • Code of conduct
• License

About

The goal of this project is to make it dead simple to add sensors to your projects. SimpleSensor is modular, you can pick and choose pieces to use from the contributed modules repo or build your own modules to custom needs. Feel free to contribute back modules, too.

In a basic use case a collection module can simply send messages along a communication module when a certain state or event is detected in a collection module. You can also orchestrate more complicated flows by communicating between modules before sending the message along communication channels.

For samples of how to integrate SimpleSensor with clients such as AEM Screens and vanilla Javascript, check out the samples branch of the contribution repository.

Modules

Modules are the building blocks of SimpleSensor. They typically have at least 4 parts:

1. Main module class
2. Config loader
3. Zero or more config files
4. An __init__.py, you must import the module class as CollectionModule (this is to simplify dynamic module imports)

The main module class extends the ModuleProcess base class, and runs on it's own thread or process. The logic of this class can be broken down into 3 stages:

1. Initialize ➡️ perform any set up needed, either in __init__() or in run() before you begin the loop.
2. Loop ➡️ main logic of the module, repeats until a message is read to shutdown.
3. Close ➡️ clean up anything that won't clean itself.

Collection Modules

Used to collect data from a sensor, check if that data means something special has occurred, and send a Message if it has.

Example modules: bluetooth (BTLE) beacon, demographic camera

1. Initialize ➡️ initialize the sensor you'll be polling, set event condition, create variables and spawn threads if needed.

2. Loop ➡️ poll the sensor; if the condition is met, make a Message instance and put it on the queue with put_message().

3. Close ➡️ join threads you spawned, clean up the sensor, and mark the module as alive=False.

Communication Modules

Used to send Messages along a communication channel.

Examples modules: MQTT, websocket server, websocket client

1. Initialize ➡️ perform logic needed to operate the communication channel and the module, for example, handshakes or opening ports.

2. Loop ➡️ poll the inQueue for messages to send along the communication channel.

3. Close ➡️ reverse whatever you did in initialize, then mark the module as alive=False.

Logger

The ThreadsafeLogger is a simple facade to add messages to the logging queue, which is an instance of multiprocessing.Queue that is shared among all modules. The logging queue is then consumed by the LoggingEngine which passes those formatted messages to the Python logging module.

The default configuration logs to stderr, as well as to a file located in the <run directory>/logs directory.

To configure custom logging parameters, change the logging config file.

Setup

There are two ways to use SimpleSensor:

Manually

1. Configure base ➡️ /config/base.conf

2. Add modules ➡️ write, download, clone

3. Configure modules ➡️ <some module>/config/module.conf and, if necessary, <some module>/config/secrets.conf

4. Run ➡️ python ./simplesensor/main.py

CLI

1. Install ➡️ pip install . from the same directory as setup.py

2. Add/configure modules ➡️ scly install --type <communication or collection> --name <module branch name>

3. Configure base ➡️ scly config --name base

4. Run ➡️ scly start

More details on the CLI can be found in the CLI readme.

Documentation

1. Shared

1.1. Message

Source: simplesensor/shared/message.py

class simplesensor.shared.message.Message(topic, sender_id, sender_type, extended_data, recipients, timestamp)

Property	Required	Type	Description
topic	Yes	String	Message type/topic
sender_id	Yes	String	ID property of original sender
sender_type	No	String	Type of sender, ie. collection point type, module name, hostname, etc
extended_data	No	Dictionary	Payload to deliver to recipient(s)
recipients	No	String or list[str]	Module name(s) to which the message will be delivered, ie. "websocket_server". - Use an array of strings to define multiple modules to send to. - Use "all" to send to all available modules. - Use "local_only" to send only to modules with low_cost prop set to True. - Use "communication_modules" to send only to communication modules. - Use "collection_modules" to send only to collection modules.
timestamp	No	ISO 8601 String	Timestamp of when the message was created

1.2. ModuleProcess

Source: simplesensor/shared/moduleProcess.py

class simplesensor.shared.moduleProcess.ModuleProcess(baseConfig, pInBoundQueue, pOutBoundQueue, loggingQueue)

Base class for modules to inherit. Implements functions that are commonly used, defines the correct queue usage and parameter order.

This should not be instantiated itself, instead you should extend it with your own module and can initialize it in the __init__() function with ModuleProcess.__init__(self, baseConfig, pInBoundQueue, pOutBoundQueue, loggingQueue).

For an example of how it can be used, see

1.3. ThreadsafeLogger

Source: simplesensor/shared/threadsafeLogger.py

class simplesensor.shared.threadsafeLogger.ThreadsafeLogger(queue, name)

Docs go here

Contributing

For contributing modules, please check out our module contribution repo

All submissions should come in the form of pull requests and will be reviewed by project contributors. Read GitHub's pull request documentation for more information on sending pull requests.

Issues

Issues should either include a proposal for a feature or, in the case of bugs, include the expected behavior, the actual behavior, your environment details, and ideally steps to reproduce. They should also ideally address actual issues with the code, not issues with setting up the environment. Please follow the issue template for consistency.

Pull Requests

Pull requests should include references to the title of the issue, and changes proposed in the pull request. Please follow the pull request template for consistency.

Code Of Conduct

This project adheres to the Adobe code of conduct. By participating, you are expected to uphold this code.