Shop OBEX P1 Docs P2 Docs Learn Events
Propeller 2 Objects: a process to involve community and share code — Parallax Forums

Propeller 2 Objects: a process to involve community and share code

Ken GraceyKen Gracey Posts: 7,386
edited 2020-06-26 03:08 in Propeller 2
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 B) 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
«1

Comments

  • Reserved post.
  • evanhevanh Posts: 15,126
    edited 2020-06-25 17:54
    Structurally, what is a smart tab built of? Does it require a word-processor like understanding of tabs, or is it built solely from space characters, or some sort of mix?

  • I suggest prefixing all VARs with something. Personally, I use an underscore prefix in all my objects - you or another user can then see at a glance throughout the code that they're not a local var.
  • JonnyMacJonnyMac Posts: 8,912
    edited 2020-06-25 18:46
    Smart tabs are built into Propeller Tool (which does in fact convert tabs to spaces). Those are what I currently use to format my P1 and P2 programs -- though I reserve the right to change should I feel I have something better. :)

    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.
  • JonnyMac wrote: »
    Smart tabs are built into Propeller Tool. Those are what I currently use to format my P1 and P2 programs -- though I reserve the right to change should I feel I have something better. :)

    Just to be clear, the information I provided to Ken are my opinions. I realize and respect that other 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
  • RaymanRayman Posts: 13,800
    I hope there can be versioning, like OBEX and GitHub had...

    I might have code for some of these things, but it's nowhere near a final version....
  • evanhevanh Posts: 15,126
    Ah, I guess that shows that I've never used PropTool for code entry.
  • ErNaErNa Posts: 1,738
    I very often include in my code a function version() that returns the version of the code. So I can decide from calling this function of an object if I linked the latest version that fits into the application.
  • ErNa wrote: »
    I very often include in my code a function version() that returns the version of the code. So I can decide from calling this function of an object if I linked the latest version that fits into the application.
    I've only ever done that with PCB revisions of the same product that had minor IO changes. Is there an advantage of a function over a version constant in the libarary?
  • SuracSurac Posts: 176
    edited 2020-06-25 21:14
    I think a form of video output is also very handy.
    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

  • JonnyMacJonnyMac Posts: 8,912
    edited 2020-06-25 21:44
    ...Spin2/PASM2 which I hope the veterans will accept.
    I think I'm considered a veteran having been using Parallax products since 1994. You will have my full support for using Spin2 and P2ASM. There's a lot to master with both, but as with their predecessors, they are clean and easy and pack a lot of punch. I understand C, but find the syntax annoying. That said, I also understand why a long-time C programmer might say the same thing about Spin. As humans we tend to like what we're used to.
  • Jon, I and others appreciate your guidance very much, however I feel this is a time, perhaps for a month, we could allow things to settle down. You have had a major influence and now is a time for softly softly... Many users of C & C++ will feel a sense of loss at this time...
  • RaymanRayman Posts: 13,800
    I've found that a fixed tab spacing of 4 works pretty well and makes things simple...
  • Cluso99Cluso99 Posts: 18,066
    Rayman wrote: »
    I've found that a fixed tab spacing of 4 works pretty well and makes things simple...
    +1
    And convert to spaces so that code doesn’t change with different tab settings!

    I’m finding VSC great for editing P2 code :)
  • Phil Pilgrim (PhiPi)Phil Pilgrim (PhiPi) Posts: 23,514
    edited 2020-06-25 23:30
    Here in the northern hemisphere we prefer two tab spaces. :)

    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
  • If you can handle a video from me, please see first post.

    Ken Gracey
  • JonnyMacJonnyMac Posts: 8,912
    edited 2020-06-26 00:25
    kg1 wrote: »
    Jon, I and others appreciate your guidance very much, however I feel this is a time, perhaps for a month, we could allow things to settle down. You have had a major influence and now is a time for softly softly... Many users of C & C++ will feel a sense of loss at this time...
    There is no reason for that. Parallax has shown that it's supportive of Eric Smith's work, and his tool is gaining traction. Would I like to see more C support from Parallax? Yes -- even though I won't use it. I practically begged Chip to rewrite the PNut compiler in C but he chose Spin instead. I find this mysterious because the PNut compiler, if coded in C (vs x86 code that exists now), could be compiled to run anywhere -- including on the P2 using FastSpin. Maybe the Spin2 compiler code for Spin2 will be translated to C by one of the expert C programmers in the community.

    Here in the northern hemisphere we prefer two tab spaces. :)
    I'm with you, Phil. When writing Python I do use four spaces, but Spin and C get two.
    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.
    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.

  • ErNaErNa Posts: 1,738
    edited 2020-06-26 11:25
    JonnyMac wrote: »
    ErNa wrote: »
    I very often include in my code a function version() that returns the version of the code. So I can decide from calling this function of an object if I linked the latest version that fits into the application.
    I've only ever done that with PCB revisions of the same product that had minor IO changes. Is there an advantage of a function over a version constant in the libarary?
    The propeller to me is a multi processor environment. I start and stop tasks according to the current goal I want to reach. I also try to have modules like incremental encoder or PWM generation that are used in different hardware. After loading a COG I first ask the version number of the program loaded to be sure to have the right version that fits the current application. This prevents me from searching bugs in case of making an error in selecting the source version.
  • I'd like to help with writing one or more of these objects in Spin2. Which ones do people already have covered?
  • Five new objects have been added to the P2 GitHub repository on Friday using this new process.

    https://github.com/parallaxinc/propeller/tree/master/libraries/community/p2

    Ken Gracey
  • David Betz wrote: »
    I'd like to help with writing one or more of these objects in Spin2. Which ones do people already have covered?
    Jump in and write what suits you -- I wouldn't worry about what others have already written; you may do something more effectively that others will learn from. From Ken's list above I have written:

    -- 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.

  • . . .and we're getting closer to defining an ESP32 object.

    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
  • I have CAN bus code that works with MCP2562. MCP2551 is NRND. MCP2562 has a pin for IO levels, good for using 5v CAN with a 3.3v micro like propeller. But given that the expected usage is industrial or automotive, I've been holding off release until I've tested it pretty well. If you want to help test this, let me know.


  • Why can"t you just put out a propeller 2 tool like you did for propeller 1. I already blew my $$$ on this P2 eval P2 accy. And all I have to work with is this flex GUI that some forum guy made up.

  • DigitalBob wrote: »
    Why can"t you just put out a propeller 2 tool like you did for propeller 1. I already blew my $$$ on this P2 eval P2 accy. And all I have to work with is this flex GUI that some forum guy made up.

    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
  • Yes, windows I loaded some other tool under prop 1 tool but didn't see any difference. You did a nice job on the prop 1, tool, Bs2, I still have that SX tool but you discontinued right after I bought it.
  • Isn't spin 2 better for the P2
  • Alpha, that's it. I loaded that, so now what. Didn't see any difference I'm still using this flex gui
  • I thought this alpha was a whole new spin2 tool. With a spin2 library, spin2 demo's etc.
  • It's in process, Bob. At the moment, Propeller Tool 2.2 can compile Spin1 and Spin2 programs. That said, you have to save the file before compiling so that PT knows what type it is. Down the road a type comment -- like used in the Stamp Editor -- will identify P1 or P2. I am taking a chance on Jeff using the same syntax so you'll see a comment with {$P2} in my P2 listings.
Sign In or Register to comment.