Photon shield shield silkscreening: Name ambiguity and tilde

Hardware
1

Both edges of the shield shield have a row of headers. Push pins or Arduino shields can plug in.

Consider the front side, right hand side of the shield shield. The top hole is marked “~SCL”; note the tilde. That same hole on the back of the board is marked D1. From other documentation one sees that SCL is one of the peripherals which can operate on this pin, pin D1. I get that.

So what does the tilde signify? Perhaps a quarter of the pins have a silkscreened tilde.

Next question: Sticking with that same signal, SCL and D1, there is a plated through hole immediately next to the black header sticking up. I assume there is a copper connection between that plated through hole and the header connector pin. Is this right? (I know, it’s a dumb question. But I got hung up thinking it might be Arduino nomenclature.)

Next question: Other documentation (https://docs.particle.io/datasheets/photon-shields/) lists three columns as follows: “Shield Photon Peripherals”. There are 20 lines in this table, one for each physical pin.

The 20th line in this table lists shield pin A5 in the first column followed by “D1 SCL,PWM,CAN_TX” .
However, the A5 name is also listed in the 9th row of the table as the Photon name:
"8 A5 SPI1_MOSI,PWM,CAN_RX"
Is this a misprint or does A5 mean two different things? If you are talking about a Photon pin it means one thing but if you are talking about a shield shield pin it means something entirely different.

Calling this “screwed up nomenclature” for a moment, this duality of names exists for A2, A3, A4, A5.

Next question: Assuming there’s a good reason for having what I would call ambiguous names, is it true that when PROGRAMMING the Photon one should use the names in the Photon column?

Perhaps things are becoming clear: If I want to PROGRAM the Photon, I look at the names silkscreened on the BOTTOM of the shield. If I program, say, pin A5 to go high, I should look on the BOTTOM of the shield to know where to electrically pick up this signal. True?

What the heck are the names on the TOP of the shield shield used for? Who would need to look at them?

2

On Arduino boards it's common to mark PWM capable pins with a tilde.

The Shield column A5 refers to the Arduino shield naming scheme and the Photon column to the Photon naming scheme - and there is little one can do about that since Arduino did set this pseudo standard and Particle just provides a bridge between its own product and Arduino shields with the Shield shield.
But it's not too complicated to figure top and bottom silk or Shield and Photon column can be used as a dictionary/translation guide between two "languages".

And yes, since the programming is done on the Photon and not the shield or an Arduino, you should use the Photon names.

Obviously people who know the Arduino nomenclature (and maybe write code for both worlds or port from one to the other)
So in this case it would have been the place to consider that:

1 Like