YonoArc supports different types of blocks:
- Blocks using YonoArc Python 3 API.
- Blocks using YonoArc Octave API.
- Blocks using ROS (Python 2 or C++).
We strongly recommend developers to create blocks using our YonoArc Python 3 API because it is feature-rich and will continue to improve.
Creating blocks can be done in two ways:
- Create a custom block right from YonoArc. This is very straightforward, so it is useful for quick prototyping or while still developing a block. This option should be your starting point. This option only supports YonoArc Python 3 API and YonoArc Octave API.
- Use the block manager to create blocks, release them to be used in any pipeline, or publish them on YonoStore.
We always recommend using custom blocks during the development phase. Using custom blocks with the ability to terminate and launch blocks while the pipeline is running using YonoArc’s Live Mode makes you always a few clicks away from trying new things or fixing bugs:
- If needed, click Show block logs under your block’s properties tab or check your block’s alerts tab to investigate issues.
- Update the code using Jupyter Notebook.
- Click Terminate then Launch for the block, not necessarily the entire pipeline. Terminating and launching a single block should be very fast since the environment of your block is already ready.
Hint: If you have a core algorithm that can run without YonoArc, it may be useful to split your work into: (a) File(s) that are YonoArc-independent and contain your core algorithm. These files can be developed and run in Jupyter Notebook without the need for YonoArc at all. (b) The main file of your YonoArc block. This file interfaces between YonoArc and your core algorithm which you have already developed. Since our APIs are simple, this file is less likely to have bugs, so this will reduce your development and debugging trials in YonoArc.
Let us first see the block attributes that will be used to create blocks regardless of their types or the way you create them.
The following are the comprehensive list of attributes for a block. Some attributes are only valid when creating a block using a specific type of block. This will be indicated between square brackets.
- Name is the name of the block in YonoArc and YonoStore.
- Description explains what the block does.
- [Custom Blocks] Folder Path is the path of the folder containing the source code of the block.
- [YonoArc Python 3 API – Custom Blocks] File Path is the path of the file containing the class representing the block. You can use a Jupyter Notebook .ipynb file and YonoArc will automatically convert it to a .py file before being executed.
- [YonoArc Python 3 API] Class Name is the name of the class representing the block.
- Input/Output Ports define the interface of the block.
- Name is the name of the port.
- Key is unique and without spaces. In YonoArc APIs, use it to identify the port of the incoming/outgoing message.
- Message is the full name of the message in the form package_name/MessageName.
- [ROS] ROS Name is the ROS topic name. This will be used for remapping when the ROS node is launched. For example, if you set ROS Name to /my_topic, YonoArc runs your ROS node using the command: rosrun package_name node_name /my_topic:=/xyz where /xyz is the actual topic having the data. In this case, your code can subscribe or publish to /my_topic and it will be automatically remapped to /xyz. For more information, please visit the ROS documentation.
- Description explains the data on the port.
- Properties allow the user to control the behavior of the block.
- Type can be one of the following:
- Text allows any arbitrary string. The default value can be configured using the Default field.
- Number allows any numeric value. The default value, upper limit, and lower limit can be configured using the Default, Min, and Max fields.
- Slider allows any numeric value in a given range using a UI slider. The default value, upper limit, and lower limit can be configured using the Default, Min, and Max fields.
- Boolean allows True or False using a UI checkbox. The default value can be configured using the Default field.
- Select allows one option from a predefined list of options. The options and the default selection can be configured using the Options and Default fields. The zero-based index of the selected option is delivered to the block.
- Button shows a button that can be clicked while the block is running. This type can be used only with YonoArc APIs and the on_button_clicked handler will be invoked when the user clicks the button.
- File/Folder Path allows the user to select any desired path from YonoDrive. Allow multiple paths should be checked if the block can handle multiple paths.
- Name is the name of the property.
- Key is unique and without spaces. In YonoArc APIs, use it to get or set the value of the property.
- [ROS] ROS Name is the ROS parameter name. This will be used for parameter remapping when the ROS node is launched. For example, if you set ROS Name to _threshold, YonoArc runs your ROS node using the command: rosrun package_name node_name _threshold:=3. In this case you can get the value of the property (i.e., 3 in this case) in your code using rospy.get_param(‘~threshold’) since it is a private parameter. For more information, please visit the ROS documentation.
- Description explains the property.
- Is required? indicates whether this property is required to be set by the user before running the block or not. This is not applicable for properties of type Button because they are only used in live mode while the block is running.
- [YonoArc APIs] Supports live updates allows this property to be updated while the block is already running. Properties of type Button, by definition, supports live updates because they are only used while the block is running.
- Type can be one of the following:
- [Custom Blocks] Git Repositories of Messages is the list of URLs and versions for the Git repositories of the messages needed by the block. Do not keep any unnecessary repositories in the list in order to avoid long launch delays.
- [YonoArc APIs] Execution Mode defines how incoming messages are delivered to the block via YonoArc APIs.
- Async: Whenever a new message arrives at any of the input ports, the message is delivered to the block.
- Sync: The messages arriving at all the input ports are time synchronized and delivered together to the block. The Interval parameter defines the delay (in seconds) with which messages can be synchronized. Note that this mode can cause messages to be dropped if they are not synchronized.
- Triggered: Whenever a new message arrives at the Primary Port (selected by you), the message along with all the latest messages from the other ports are delivered to the block. Note that this mode means that messages on the secondary ports may be dropped or delivered multiple times.
- Periodic: Deliver the latest messages at all the input ports every time interval (specified by the Interval parameter, in seconds) regardless of how fast the messages arrive. Note that this mode means that messages can be dropped (or delivered multiple times) if they arrive faster (or slower) than the desired interval since only the latest messages are delivered every time interval.
- [Custom Blocks] Environment and Version are for the runtime environment of the block.
- Minimum Resources specifies the minimum resources that is recommended for the block. It can be any multiple of C0.1 (0.1 CPU core and 0.4GB RAM) or GK0.1 (0.1 Tesla K80 GPU, 0.6 CPU core, and 5.6GB RAM). This value can be adjusted later by the user of the block in YonoArc.
- [Non-Custom Blocks] Toolbox is the YonoArc toolbox in which the block would appear.
- [Non-Custom Blocks] Enable scaling determines whether this block can be scaled or not. Check this checkbox if your block is stateless.
Creating Custom Blocks
To create a custom block, follow this straightforward procedure:
- Develop a block based on our YonoArc APIs: Python 3 API or Octave API.
- Click the + button on the upper-left corner of the canvas then drag the Custom Block into the canvas.
- Click the settings icon on the block and specify the required block attributes as described above.
- Connect your custom block with other blocks and launch the pipeline.
Creating Blocks Using the Block Manager
You can navigate to the block manager from YonoArc by clicking the + button on the upper-left corner then clicking the Block Manager button at the bottom. The block manager enables you to create a project for each block you develop..
To create a block, follow this procedure:
- Create a project.
- Click Create project.
- Specify the project name, type, environment, the source code path (a Git repository or a YonoDrive folder), and the list of URLs and versions for the Git repositories of the messages needed by all the blocks in the project.
- For ROS-based projects, the source code directory is the catkin workspace.
- At the end of this step, the status of the project becomes Created.
- Build the project.
- Select the project then click Build.
- This process may take a few minutes and you may be asked to select a resource model for the build process.
- The project status turns from Created to Waiting (i.e., allocating resources) to Building.
At the end of this step, the status of the project becomes Release Ready or Failed.
- Enter/Update the attributes of the block.
- Click the Blocks tab.
- Select the project from the drop-down list.
- Select “Unreleased” from the version drop-down since the new version hasn’t been released yet.
- The block manager shows the list of blocks discovered during the build process.
- Delete all the candidate blocks, except the correct one representing your project. Simply select your block, click Invert to select all except this block, then click Delete.
- Enter the attributes of your block and click Save.
- Release the project.
- Select the project then click Release.
- Specify the version of the project in the major.minor.patch format.
- At the end of this step, the status of the project becomes Released.
- At this point, the block is released and you can use it in YonoArc.
Working with Existing Projects
In the main view of the Block Manager under the Projects tab, if you select a project from the table, you can perform various actions using the buttons at the top:
- Build the project. This is needed only for a new project or an existing project whose source code or basic project info has changed. This action fetches your source code from YonoDrive or GitLab (depending on your project settings) and builds the project based on the basic info of the project, including the type of the project and the messages needed.
- Cancel the build process if the project status is either Waiting or Building.
- Release the project if the project is Release Ready. You will be asked to enter the version of the release in the major.minor.patch format.
- New release which creates a new unreleased version of the project. You can then build the project if the source code of the project has changed or edit the info of the block under the blocks tab if the source code hasn’t changed.
- Edit the essential info of the project.
- Show logs of the build process.
- Share the project with your teams. You should select one or multiple teams and click Apply. All members in the selected teams will have full read/write access to the project in the Block Manager and its block in YonoArc.
- Delete the latest version of the project.
- Delete all versions of the project.
Some actions may be disabled depending on the current status of the project.