srobo / j5 Goto Github PK

View Code? Open in Web Editor NEW

9.0 12.0 4.0 3.02 MB

j5 - Framework for Robotics APIs

License: MIT License

Python 99.59% Shell 0.19% Makefile 0.22%

robotics robotics-programming robotics-library robotics-competition hacktoberfest

j5's Introduction

j5

j5 Framework - Creating consistent APIs for robotics

What is j5?

j5 is a Python 3 framework that aims to make building consistent APIs for robotics easier. It was created to reduce the replication of effort into developing the separate, yet very similar APIs for several robotics competitions. Combining the common elements into a single library with support for various hardware gives a consistent feel for students and volunteers. This means more time to work on building robots!

How do I use j5?

j5 is designed to never be visible to students. It sits behind the scenes and works magic.

from robot import Robot

r = Robot()
r.motor_boards[0].motors[1] = 0.5

The above code is likely to be familiar to any student who has competed in one of the below competitions. However, it is not a trivial problem to make this code portable across the platforms. For example, the motor board for Student Robotics is a separate board to the brain board, but is built into the same board for HR RoboCon.

j5 lets competition vendors define how the basic parts of the apis are accessed. A robot can thus be constructed from any combination of parts from various organisations.

from j5 import BaseRobot
from j5.backends.hardware.sr.v4 import (
    SRV4MotorBoardHardwareBackend,
    SRV4PowerBoardHardwareBackend,
    SRV4ServoBoardHardwareBackend,
)
from j5.boards import BoardGroup
from j5.boards.sr.v4 import MotorBoard, PowerBoard, ServoBoard


class Robot(BaseRobot):
    """My Competition Robot."""

    def __init__(self) -> None:
        self._power_boards = BoardGroup.get_board_group(
            PowerBoard,
            SRV4PowerBoardHardwareBackend,
        )
        self.power_board = self._power_boards.singular()

        self.motor_boards = BoardGroup.get_board_group(
            MotorBoard,
            SRV4MotorBoardHardwareBackend,
        )
        self.motor_board = self.motor_boards.singular()

        self.servo_boards = BoardGroup.get_board_group(
            ServoBoard,
            SRV4ServoBoardHardwareBackend,
        )
        self.servo_board = self.servo_boards.singular()

Competitions

We intend to support the kits of the following robotics competitions:

As of 2023, j5 is written and maintained by the Student Robotics Kit Team.

sbot, a j5 based API, was successfully deployed to over 100 users in August 2019. This is the first known case of a real-world deployment of a j5 based API.

If you are interested in adding support for your hardware or building your own API, please get in touch.

Contributions

This project is released under the MIT Licence. For more information, please see LICENSE.

j5 contributors refers to the people listed in the CONTRIBUTORS file.

The CONTRIBUTORS file can be generated by executing CONTRIBUTORS.gen. This generated file contains a list of people who have contributed to the j5 project.

More information about contributing, and how to contact contributors can be found in our docs

j5's People

Contributors

Stargazers

Watchers

Forkers

shivam60 udhayacommits trickeydan raccube

j5's Issues

Fix "method_complexity" issue in j5/backends/base.py

Function __new__ has a Cognitive Complexity of 18 (exceeds 5 allowed). Consider refactoring.

https://codeclimate.com/github/j5api/j5/j5/backends/base.py#issue_5c577b82c8c5d00001000033

Support SourceBots Arduino

Requires:

Servos - #42
GPIO - #43
Ultrasound - This may or may not want to be a component. Consider this when we get here.

Incomplete Type Definitions

There are some types put as Any and some missing types.

Apparently these can be fixed?

[FEATURE] Hardware Support

We should aim to support hardware.

Specific hardware boards should be listed as separate issues below:

SR v4 Power Board
SR v4 Motor Board
SR v4 Servo Board
SR Ruggeduino
SourceBots Arduino / Servo Board

Create Servo Component

Docs don't push to RTD

Support SR v4 Power Board

Support SR v4 Power Board.

Prerequisites:

~~Button Support~~ - #44
~~Power Output Support~~ - #61
~~Battery (voltage / status)~~ - #62
~~Piezo~~ - #60

Parameter descriptions and typing

e.g

def format_unit(value, unit):
    """
    Formats the given value as a human readable string using the given units.

    :param float|int value: a numeric value
    :param str unit: the unit for the value (kg, m, etc.)
    :rtype: str
    """
    return '{} {}'.format(value, unit)

We should consider this: https://pypi.org/project/sphinx-autodoc-typehints/

[QUESTION] How does proposed class structure cope with differing capabilities of boards?

How does the j5's class structure cope with the fact that in some environments (i.e. competitions) two APIs are physically implemented by two different boards, while in other environments they are implemented by the same board?

As a concrete example, Student Robotics provides a servo interface via a servo board and a GPIO interface via an Arduino, but Source Bots provides both of these interfaces via an Arduino (with an attached servo driver shield). Therefore code to operate a servo may look like:

robot.servo_boards[0].servos[0] = position

in a Student Robotics environment while looking like:

robot.arduinos[0].servos[0] = position

in a Source Bots environment. This inconsistency feels counterproductive to the goal of j5.

As another example, Arduinos run different firmwares in different environments: the Source Bots Arduino firmware has builtin support for ultrasound sensors while the Student Robotics firmware does not.

[DOCS]: Class Structure

Update CircleCI to 3.7

CircleCI is on Python 3.6 currently, we should update.

Also add it to the Pipfile.

READ ME FIRST: How to contribute

How to contribute

Pick an issue that is currently unassigned.
Assign yourself to that issue.
Write some code!
Ensure that you lint, type and unit test your code.
Submit a Pull Request, including Fixes #issuenum in the description
Make sure that the tests pass.
Sign the CLA.
Wait for Code review to be approved.
Merge!

Fix "method_complexity" issue in j5/boards/base.py

Function __getitem__ has a Cognitive Complexity of 9 (exceeds 5 allowed). Consider refactoring.

https://codeclimate.com/github/j5api/j5/j5/boards/base.py#issue_5c577b82c8c5d00001000034

[QUESTION] Are BackendGroups extensible?

From my understanding of how j5 is currently structured (please correct me if I'm wrong), it looks like a BackendGroup must have knowledge of every type of board that could provide. It also doesn't look like HardwareBackendGroup (and presumably other types of BackendGroup too, once they are defined) is competition-specific, so a HardwareBackendGroup therefore needs to have every board used in every competition hardcoded into it. Additionally, I'm not certain but it sounds like this structure would restrict the ability for end users to define their own boards using the j5 API.

If this is indeed true, my proposal would be for BackendGroups to be initially empty, and to have each Backend register itself into its corresponding BackendGroup at the time of class definition.

repr

The return value of __repr__ should look like a valid Python expression that could be passed into eval() to create an object with the same value (or as close as)

https://docs.python.org/3/library/functions.html#repr

[BUG]: Bad naming convention on BackendGroup

The BackendGroup class currently has a supported_boards property. This is confusing, as it actually returns a dictionary of boards to their backends, but should probably return a List of supported boards.

[FEATURE] Locks

We need to have a lock to prevent multiple robot processes. Suggestions are to use /var/run, but that does lock it down to be platform specific which we do not want.

Use Collections metaclasses to do BoardGroups

Autodeploy releases to PyPI

Possible methods:

Git Tags (But need to restrict permissions)
GitHub Releases, requires a separate server to receive the webhook.

Fix "E261" issue in j5/boards/base.py

At least two spaces before inline comment

https://codeclimate.com/github/j5api/j5/j5/boards/base.py#issue_5c5781f87c70f4000100003a

Fix "E261" issue in j5/boards/j5/demo.py

At least two spaces before inline comment

https://codeclimate.com/github/j5api/j5/j5/boards/j5/demo.py#issue_5c5781f87c70f4000100003c

[FEATURE] Mock Hardware

We should aim to support hardware in mock.

Specific hardware boards should be listed as separate issues below:

SR v4 Power Board
SR v4 Motor Board
SR v4 Servo Board
SR Ruggeduino
SourceBots Arduino / Servo Board

[FEATURE] BoardGroup repr

Board has __repr__, so it makes sense for BoardGroup to have one too.

Add Piezo Component

Create Vision Components

We need to find a nice way to model fiducial markers without restricting ourselves to a particular library.

My initial suggestions:

Camera Component representing a camera
Token - data type of a token
Vector - The distance and direction of a token from a camera.
- Spherical coordinates
- Cartesian coordinates, we need to support this for less knowledgeable competitors
Orientation - The orientation of a token in 3D space

[FEATURE] Make Safe.

Things should be nice and safe.

[FEATURE] Fix integer indices on boards being non-deterministic

Remove integer indices
Sort by serial number before looking.

[DOCS]: Getting Started

[FEATURE] Support Start Button

Support start button, but not enforce it

Support SR v4 Motor Board

Requires MotorOutput - #41

BoardGroup.iter should return a disposable object, not itself

Currently, BoardGroup.__iter__ returns self, and uses an attribute of self to maintain state. This confuses the lifetime of a collection with the lifetime of an iteration over that collection. This method should really return a distinct object encapsulating the statefulness of iteration (self.boards.values(), for example).

If this gets a 👍 or two I'll go ahead and make a PR.

Support SR v4 Servo Board

Require Servo Component - #42

Support SR Ruggeduino

Requires GPIO Pin - #43

We need to think about how to support direct communication. Perhaps some sort of serial component?

Enforce type hints on all code

Now that the majority of the project has type hints, we should try to keep it that way. We can enforce this by changing our mypy settings to enforce code has type hints.

I propose we enable the following flags, though I'm open to discussion (these are the command line flags but they have equivalent .cfg options):

--disallow-untyped-defs
--disallow-incomplete-defs
--no-implicit-optional (this one is more personal preference and less to do with maintaining type coverage)

Docs for the above flags can he found here

Create GPIOPin Component

Review whether BoardGroups should be ordered or not

There is no inherent order to the boards attached to a robot. We should make a decision whether we want to keep this notion (requiring users to address boards by serial number), or to assign an order (in which case we need to be explicit about what that order is e.g. sort by serial number)

This is relevant to #23.

I'm happy to implement the outcome of this decision in a PR.

No check for setup method call

The board.setup() method can easily be not called by the vendor, leading to a lack of safety for that board.

Possible fixes:

Use __new__
In the constructor (causes the same issue as super())
Metaclass