Please implement Timing Diagrams

Question

I'd like to create Timing Diagrams with PlantUML.

What I would exactly need can be seen here:
http://www.uml-diagrams.org/examples/timing-diagram-example-website.png
and here:
http://wavedrom.com/tutorial.html

Answer 1

Timing Diagrams have been added to last version: http://plantuml.com/timing-diagram

Answer 2

It's not possible to do this with PlantUML (yet).

However, the drawing does not look too difficult to implement.

The real issue is the textual syntax for such a diagram. So we need your contribution : could you make a syntax proposition that would describe your example http://www.uml-diagrams.org/examples/timing-diagram-example-website.png ?

If you find a nice, human understandable and complete textual description for such an example, we would be glad to implement it.

What do you think about it ?

Comments

That sounds great, so first of all thanks a lot for your offer!

I invested some time to define a proper syntax for this, what do you think?

It describes the diagram from here: http://www.uml-diagrams.org/timing-diagrams.html

That's the image: http://www.uml-diagrams.org/timing-diagrams/timing-diagrams-overview.png

@startuml
  Type: Timing

  printTimeRuler
  printToken

  Tick: 100ms
  TickStart: A1
  Events: [A0/B0]..[A1/C0/D0][B1]..[B2]..[C1]....[C2]..[B3]....[B4/C3/D1]..[D2]..[B5]..[D3]..[B6].[B7].[B8].[A2]

  robust "Web Server":   [Waiting#D0]..[Processing#D1]..["Sending response"#D2]...[Waiting#D3]
  robust "DNS Resolver": [Idle#C0]..[Processing#C1]..[Idle#C2]...[X#C3]
  robust "Web Browser":  [0#B0]..[1#B1]..[2#B2]..[1#B3]..[1#B4]..[2#B5]..[1#B6]..[1#B7]..[0#B8].. { 0=Idle, 1=Processing, 2=Waiting }
  concise "Web User":    [0#A0]..[42#A1]..[2#A2].. { 0=Idle, 42=Waiting, 2=Viewing }

  "Web User"#A1     ->    "Web Browser"#B1  : URL
  "Web Browser"#B2  ->    "DNS Resolver"#C1 : resolve URL
  "DNS Resolver"#C1 |<->| "DNS Resolver"#C2 : {0..400 ms}
  "DNS Resolver"#C2 -->   "Web Browser"#B3
  "Web Browser"#B4  ->    "Web Server"#D1   : {50..200 ms}
  "Web Server"#D1   |<->| "Web Server"#D3   : {200..800 ms}
  "Web Server"#D2   -->   "Web Browser"#B5  : HTTP response
  "Web Browser"#B5  |<->| "Web Browser"#B6  : {100..500 ms}
  "Web Browser"#B7  |<->| "Web Browser"#A2  : Show page

  note "Web Server"#B3:                          state change
  note left of "DNS Resolver":                   lifeline robust diagram
  note left of "Web User":                       lifeline concise diagram
  note right of "Web Server"#"Waiting":          state or condition
  note right of "Web Server"#"Processing":       state or condition
  note right of "Web Server"#"Sending response": state or condition
@enduml

Type: (optional) to give the diagram... as far as I understood plantuml is trying to guess the correct diagram type, maybe it's easier to give it directly?

printTimerRule: (optional) if given timer rule is printed

printToken: (optional) if given all used tokens will be printed what could be useful to find the bug if diagram doesn't look as expected

Tick: (optional) if given each elemten (Event and "dot") in Events line has a duration of one tick, if not given each event in Events will be numbered and this number will be used for the time ruler

TickStart: (optional) position where ticks printing should start

Events: (mandatory) each event must be given in square bracket, more than one event can be given if they occure at the same time but has to be separated with a slash. Each dot consumes a tick if Tick is given otherwise they are just for better readability but will be ignored.

robust <lifeline>: specifies a single lifeline. After the colon the lifeline can be described. Each state change has to be given in squared brackets, the belonging event must be separated by a #. States can be names or indices, in case of indices a list within curly brackets have to be given where a name has been given for each index, if an index doesn't belong to a name the state name will be the index itself. An event named X means the lifeline ends here. Dots can be used but they are just for better readability.

concise <lifeline>: similar to "robust <lifeline>:" but diagram will be a concise one instead of a robust one.

messages can be defined as usual "state1" -> "state2" but separated with a # the correct event has to be given to specify exact positions.

notes can be defined as usual but for participants it's possible to give any lifeline, any state or any event.

---

Thanks for your syntax proposal.
Finding a right syntax is difficult, and the best way to achieve this goal is to do many tries.

Our experiments on other diagram types show that it is only while playing with syntaxes that best ideas do emerge.

Here are some key principles that we'd like to stick to:

- syntax should be short
- syntax should be easy to read. Ideally, even if you don't know PlantUML, you should be able to get the meaning of the diagram just by reading the text
- when you want to change a diagram, you should be able to do so without editing the whole diagram text
- PlantUML should be able to guess the correct diagram type on his own

So your syntax is a good start. We like the robust/concise syntax.
In this first alpha implementation, only "robust" is supported.
You can download this alpha here https://dl.dropboxusercontent.com/u/13064071/plantuml.jar

And try the following working example:

@startuml
robust "Web Browser" as WB
robust "Web User" as WU

@0
WU is Waiting
WB is Idle

@200
WB is Proc.

@300
WB is Waiting

@500
WU is ok
@enduml

Do not focus on the drawing itself which is somehow ugly. The goal at this point is to focus on the syntax only.

We are going to implement in that order:
1) "concise" lifeline
2) Message handling

Currently, the @200 syntax works only with number. So adding a new event in the middle of the diagram forces you to renumber all events. Maybe we will support something like @+100 :

So the following diagrams would give the same result (not working yet):
@startuml
robust "Web Browser" as WB
robust "Web User" as WU

@0
WU is Waiting
WB is Idle

@+200
WB is Proc.

@+100
WB is Waiting

@+200
WU is ok
@enduml


As I said, it would be nice if you could try our syntax proposal with your real-life diagrams. Playing with it will probably gives you new ideas, so do not hesitate to do feedback.
Please feedback also if you do not agree with us on our proposal.
This is the way we will let the right syntax emerge.

Thanks

---

Sorry, I didn't find any time answering earlier...

First of all, thank you very much for the feature, in general it's really great!

I used it the last week and there are a few things I noticed:
1) robust and concise is interchanged

2) often it would be useful to give the diagram in "reverse" order, means chosing one diagram giving the actions instead of vice versa, i.e.:

@startuml
concise "Web Browser" as WB
concise "Web User" as WU

@WB
0 is Idle
200 is Proc
300 is Waiting

@WU
0 is Waiting
500 is ok

@enduml

AND

@startuml
concise "Web Browser" as WB
concise "Web User" as WU

@WB
0 is idle
+200 is Proc.
+100 is Waiting

@WU
0 is Waiting
+500 is ok
@enduml

In cases where you have just one diagram, what is very common for me,  you get a very compact and therefore easily readable diagram description.

I think it's not necessary to interlock them. It's not very likely that someone wants to mix them but even if so it doesn't add more inconsistencies than already exist and it probably makes the implementation easier.

3) having the states at the beginning of the robust diagram and not at the state switch would be more UML like and furthermore you get some space for notes:

@startuml
robust "Web Browser" as WB
concise "Web User" as WU

@0
WU is Idle
WB is Idle

@100
WU -> WB : URL
WU is Waiting : "some note" <-- this note could be placed at the state switch position above the concise diagram
WB is Processing : "some other note" <-- this note could be placed where Processing stands currently

@300
WB is Waiting

@enduml


What do you think?

---

> Sorry, I didn't find any time answering earlier...
No problem. Take your time! There is no reason to rush here.

Many thanks for your suggestions, they indeed greatly improve the language!
So here is a new beta https://dl.dropboxusercontent.com/u/13064071/plantuml.jar

Point 1) 2) 3) are fixed

For example, following examples are working:

@startuml
concise "Web Browser" as WB

0 is idle
+200 is Proc.
+100 is Waiting

@enduml

@startuml
robust "Web Browser" as WB
concise "Web User" as WU

@0
WU is Idle
WB is Idle

@100
WU -> WB : URL
'We've just removed the quotes
WU is Waiting : some note
WB is Processing : some other note

@300
WB is Waiting
@enduml

Several points are still to be done:
- constraints (like {200..700ms} in the original example). Any idea about the syntax ?
- allowing initial states (that is, before @0 )
- the drawing is not very pretty: what about some background colors in the "concise" drawing ?
- ...

Please go on with your tests and suggestions!