Propeller 2 Objects: a process to involve community and share code
Ken Gracey
Posts: 7,392
Hello Propeller Community,
With the release of an Alpha Propeller Tool, the start-up of the Propeller Live Forum - Early Adopter Series meetings, tools like FlexGUI and fastspin, and the expected placement of the first production order by Parallax, it's time for us to take some steps to help get the example object efforts organized. You've seen some of this process start without much communication from us, like a transition from OBEX to GitHub. We also haven't spoken about what languages we'll officially support, so I'll tell you now: Spin2/PASM2 and MicroPython for P2. If you're using fastspin, we may find a way to make Spin2 objects run there as well (and vice-versa), but not at this moment.
There are three ways to get objects to Parallax so we can distribute them to the community:
(1) Send a zip to developer@parallax.com
(2) Submit them via GitHub as issues here https://github.com/parallaxinc/propeller/issues
(3) Fork the repo, pull requests via the above GitHub
Thank you,
Ken Gracey
=========
To get started, @JonnyMac provided a list of objects that should be available with a Propeller 2 formal release (that date is 16 weeks after our production order has been placed). We can edit, add, and notate this list based on your comments. We've opted to start it here instead of a wide-open Google doc since this is fewer clicks away for forum members.
The objects and drivers listed in this document should be available for the P2 coincident with the formal release. Each should have documentation and examples to help engineers and enthusiasts that are new to the P2 get up and running very quickly.
CRITICAL OBJECTS/DRIVERS
The objects/drivers list below should be considered mission-critical for the official P2 launch as they provide necessary tools for engineers and enthusiasts to build apps and discrete device objects.
Full-Duplex Serial
Primary use is for terminal and terminal-like device IO and simple debugging. Should include features to format output cleanly and easily as is available in other languages (think printf). This object should allow the user to attach multiple ports with references to external buffers
Flash Storage
Standard designs will include a flash chip to hold the user program hence; access to space on the flash should be available. This object should work cooperatively with the SD/File System object for advanced designs.
SD/File System
Provide multi-file access to SD card. This object should work cooperatively with the Flash Storage object for advanced designs.
Reference:
http://elm-chan.org/fsw/ff/00index_e.html (full)
http://elm-chan.org/fsw/ff/00index_p.html (small system)
SPI Driver (smart pins)
This driver should support all SPI modes and use smart pins for high-speed access. Note that this driver could be a subsystem of the Flash and SD objects. Would also be the basis of many device/sensor objects.
I2C Driver
This driver should provide basic I2C communication (initialize bus, start, write, read, stop) at speeds from 25kHz to 400kHz. This driver would serve as the basis of many sensor device/sensor objects.
OLED Driver
This driver should include a generic graphics component and be resolution-independent. Variations could support SPI and I2C interfaces.
WiFi Bridge
Couple the ESP32 via SPI to create a WiFi connection for the P2. Targeting the ESP32 brings BT/BLE into the mix as well. The HiFive1 (Rev
controller uses the ESP32 in this manner.
Floating Point Math
This could be a translation – with optimized P2ASM – of Cam Thompson’s P1 object.
OBJECTS FOR INDUSTRIAL CONTROL
Half-Duplex RS-485
This object should support one or two channels (for bridging) with external (application controlled) buffers for each channel.
MODBUS RTU
This object would be a parent layer to the Half-Duplex RS-485 object. MODBUS is the primary protocol used in systems with RS-485 networks (ICS, etc.).
CAN BUS
It may be possible to create a cog-based read/write object that targets MCP2551 interface chip. A cogless SPI driver would target the MCP2515 CAN interface chip (which also drives the MCP2551). CAN is primarily used in automotive systems, but is seeing increased usage in ICS.
Ethernet Interface (wired)
This object will allow the P2 to be part of a standard network wired network.
Encoder Interface (smart pins)
Object should provide absolute position and delta per user-selected period using two smart pins.
Analog Input (smart pins)
Analog Output (smart pins)
PWM Output (smart pins)
DC Motor Control (smart pins)
This is an application of PWM.
Servo Controller (smart pins)
A simple driver (position only) can be cogless; an advanced driver that supports ramping (ideally with curve fitting) would require a management cog to update servos.
OBJECTS FOR MAKERS, ARTISTS
Smart Pixel Driver
Should be capable of running any of the popular pixel modules (e.g., WS2812).
DMX Output
Provide standard DMX output (through RS-485 interface) with the ability to tailor the size of the universe gap between transmissions.
DMX Input
This object will allow show-control artists to trigger effects and props using values in the DMX stream (this is something Disneyland does quite frequently).
WAV Player
Ideally, this object would be capable of mixing/playing two simultaneous WAV audio files.
SUGGESTED CODE FORMATTING GUIDELINES
Generally, the code should look more like C or Python than BASIC or Pascal (operators notwithstanding). As Spin is not a case-sensitive language, it makes sense to minimize the use of uppercase.
Blocks
The block keywords (con, obj, var, pri, pub, and dat) are in lowercase, aligned with column one of the listing, and followed by a single blank line. Elements within a block are indented by two spaces.
Block identifiers should be proceeded by two blank lines.
CON Blocks
It is good practice to start with program information, followed by timing constants, IO pin constants, then program constants. Putting each of these groups in separate con blocks is an advantage when using an editor like Propeller Tool that provides background shading by block.
Elements defined in con blocks use UPPERCASE letters with underscores and numbers as is helpful.
Smart Tabs: 2, 64
OBJ Blocks
Object names are lowercase, with the filename specified as required by the host operating system. It is good practice to include a line comment per object to notate the use of additional cogs.
Smart Tabs: 2, 64
VAR Blocks
Variable names are defined using lowercase or camelCase notation.
Underscores may be included with a special prefix to define special-purpose variables, e.g., p_str to define a pointer to a string.
Smart Tabs: 2, 8, 64
PUB and PRI Blocks
Method names are defined in lowercase using underscores to separate words. Return variables and local variables are defined in lowercase or cameCase notation.
Smart Tabs: 2, 4, 6, 8, 10, 12, 64
DAT Blocks
Preinitialized value names are defined using PascalCase notation. Assembly code is defined in lowercase.
Smart Tabs: 2, 8, 16, 24, 32, 56, 64
With the release of an Alpha Propeller Tool, the start-up of the Propeller Live Forum - Early Adopter Series meetings, tools like FlexGUI and fastspin, and the expected placement of the first production order by Parallax, it's time for us to take some steps to help get the example object efforts organized. You've seen some of this process start without much communication from us, like a transition from OBEX to GitHub. We also haven't spoken about what languages we'll officially support, so I'll tell you now: Spin2/PASM2 and MicroPython for P2. If you're using fastspin, we may find a way to make Spin2 objects run there as well (and vice-versa), but not at this moment.
There are three ways to get objects to Parallax so we can distribute them to the community:
(1) Send a zip to developer@parallax.com
(2) Submit them via GitHub as issues here https://github.com/parallaxinc/propeller/issues
(3) Fork the repo, pull requests via the above GitHub
Thank you,
Ken Gracey
=========
To get started, @JonnyMac provided a list of objects that should be available with a Propeller 2 formal release (that date is 16 weeks after our production order has been placed). We can edit, add, and notate this list based on your comments. We've opted to start it here instead of a wide-open Google doc since this is fewer clicks away for forum members.
The objects and drivers listed in this document should be available for the P2 coincident with the formal release. Each should have documentation and examples to help engineers and enthusiasts that are new to the P2 get up and running very quickly.
CRITICAL OBJECTS/DRIVERS
The objects/drivers list below should be considered mission-critical for the official P2 launch as they provide necessary tools for engineers and enthusiasts to build apps and discrete device objects.
Full-Duplex Serial
Primary use is for terminal and terminal-like device IO and simple debugging. Should include features to format output cleanly and easily as is available in other languages (think printf). This object should allow the user to attach multiple ports with references to external buffers
Flash Storage
Standard designs will include a flash chip to hold the user program hence; access to space on the flash should be available. This object should work cooperatively with the SD/File System object for advanced designs.
SD/File System
Provide multi-file access to SD card. This object should work cooperatively with the Flash Storage object for advanced designs.
Reference:
http://elm-chan.org/fsw/ff/00index_e.html (full)
http://elm-chan.org/fsw/ff/00index_p.html (small system)
SPI Driver (smart pins)
This driver should support all SPI modes and use smart pins for high-speed access. Note that this driver could be a subsystem of the Flash and SD objects. Would also be the basis of many device/sensor objects.
I2C Driver
This driver should provide basic I2C communication (initialize bus, start, write, read, stop) at speeds from 25kHz to 400kHz. This driver would serve as the basis of many sensor device/sensor objects.
OLED Driver
This driver should include a generic graphics component and be resolution-independent. Variations could support SPI and I2C interfaces.
WiFi Bridge
Couple the ESP32 via SPI to create a WiFi connection for the P2. Targeting the ESP32 brings BT/BLE into the mix as well. The HiFive1 (Rev
controller uses the ESP32 in this manner.Floating Point Math
This could be a translation – with optimized P2ASM – of Cam Thompson’s P1 object.
OBJECTS FOR INDUSTRIAL CONTROL
Half-Duplex RS-485
This object should support one or two channels (for bridging) with external (application controlled) buffers for each channel.
MODBUS RTU
This object would be a parent layer to the Half-Duplex RS-485 object. MODBUS is the primary protocol used in systems with RS-485 networks (ICS, etc.).
CAN BUS
It may be possible to create a cog-based read/write object that targets MCP2551 interface chip. A cogless SPI driver would target the MCP2515 CAN interface chip (which also drives the MCP2551). CAN is primarily used in automotive systems, but is seeing increased usage in ICS.
Ethernet Interface (wired)
This object will allow the P2 to be part of a standard network wired network.
Encoder Interface (smart pins)
Object should provide absolute position and delta per user-selected period using two smart pins.
Analog Input (smart pins)
Analog Output (smart pins)
PWM Output (smart pins)
DC Motor Control (smart pins)
This is an application of PWM.
Servo Controller (smart pins)
A simple driver (position only) can be cogless; an advanced driver that supports ramping (ideally with curve fitting) would require a management cog to update servos.
OBJECTS FOR MAKERS, ARTISTS
Smart Pixel Driver
Should be capable of running any of the popular pixel modules (e.g., WS2812).
DMX Output
Provide standard DMX output (through RS-485 interface) with the ability to tailor the size of the universe gap between transmissions.
DMX Input
This object will allow show-control artists to trigger effects and props using values in the DMX stream (this is something Disneyland does quite frequently).
WAV Player
Ideally, this object would be capable of mixing/playing two simultaneous WAV audio files.
SUGGESTED CODE FORMATTING GUIDELINES
Generally, the code should look more like C or Python than BASIC or Pascal (operators notwithstanding). As Spin is not a case-sensitive language, it makes sense to minimize the use of uppercase.
Blocks
The block keywords (con, obj, var, pri, pub, and dat) are in lowercase, aligned with column one of the listing, and followed by a single blank line. Elements within a block are indented by two spaces.
Block identifiers should be proceeded by two blank lines.
CON Blocks
It is good practice to start with program information, followed by timing constants, IO pin constants, then program constants. Putting each of these groups in separate con blocks is an advantage when using an editor like Propeller Tool that provides background shading by block.
Elements defined in con blocks use UPPERCASE letters with underscores and numbers as is helpful.
Smart Tabs: 2, 64
OBJ Blocks
Object names are lowercase, with the filename specified as required by the host operating system. It is good practice to include a line comment per object to notate the use of additional cogs.
Smart Tabs: 2, 64
VAR Blocks
Variable names are defined using lowercase or camelCase notation.
Underscores may be included with a special prefix to define special-purpose variables, e.g., p_str to define a pointer to a string.
Smart Tabs: 2, 8, 64
PUB and PRI Blocks
Method names are defined in lowercase using underscores to separate words. Return variables and local variables are defined in lowercase or cameCase notation.
Smart Tabs: 2, 4, 6, 8, 10, 12, 64
DAT Blocks
Preinitialized value names are defined using PascalCase notation. Assembly code is defined in lowercase.
Smart Tabs: 2, 8, 16, 24, 32, 56, 64
Comments
Just to be clear, the information I provided to Ken are my opinions. I realize and respect that others will see and do things differently. The formatting guidance is what I give to my clients who want to embark on updating their own code, especially if they're coming from another platform.
As JonnyMac pointed out, we are not enforcing any standards. Writing code involves many personal preferences. Many of us will use JonnyMac's code and he often follows a template which will be in the Propeller Tool (and hopefully FlexGUI, too). If it's Spin2/PASM2, you may wish to adopt his formatting guidelines as your own.
Ken Gracey
I might have code for some of these things, but it's nowhere near a final version....
Sure there are many output variants the P2 can provide now but at least some form of
simple ANSI terminal output on VGA and HDMI will be nice. USB mouse/keyboard input or PS2 mouse/keyboards
also it would be super handy to have a video output option like the C64 had with perhaps 256 indexed colors and Sprites
And convert to spaces so that code doesn’t change with different tab settings!
I’m finding VSC great for editing P2 code
Seriously, though, the uneven tab spacing in PropTool is there for a reason -- mainly to make PASM formatting, with its conditionals ahead of the opcode, easier. I wouldn't want that to change. It also helps with the alignment of Spin comments. The only time it gets a little annoying is when there is deep nesting in Spin. But that's a small price to pay.
-Phil
Ken Gracey
I'm with you, Phil. When writing Python I do use four spaces, but Spin and C get two.
Yep. I do set a lot of stops in my pub and pri blocks to accommodate deep nesting -- though I do try to minimize that as well.
https://github.com/parallaxinc/propeller/tree/master/libraries/community/p2
Ken Gracey
-- Full-duplex serial
-- SPI driver (PASM2 bit-banged)
-- I2C driver
-- Half-duplex RS-485 (1 channel)
-- Quadrature encoder interface
-- Analog input
-- PWM output
-- DC motor control
-- Servo control
-- Smart pixel driver (1-wire, 800kHz)
-- Smart pixel driver (APA102c)
-- DMX output
Not all are published, and there are more in the P2 repository that aren't on the lists.
As JonnyMac said, all are welcome to participate. You needn't be a professional coder; we learn from eachother, update and share code along the way.
Ken Gracey
Are you asking about the Propeller Tool for Windows? It's here https://www.parallax.com/downloads/propeller-tool-software-windows-spin-assembly
Ken Gracey