diff --git a/.gitignore b/.gitignore index 303a6ba..aed62ea 100644 --- a/.gitignore +++ b/.gitignore @@ -10,4 +10,4 @@ RELEASE-VERSION build # Sphinx -doc/srcdoc/_build +doc/_build diff --git a/Makefile b/Makefile index 9c4daef..4a087e0 100644 --- a/Makefile +++ b/Makefile @@ -9,10 +9,8 @@ clean: @rm -rf html @mkdir html -doc: doc/*.md - @echo "Generating html tree" - @bin/make_doc.py - $(MAKE) -C doc/srcdoc html +doc: + $(MAKE) -C doc html demo: @bin/secop-server -q demo & diff --git a/doc/srcdoc/Makefile b/doc/Makefile similarity index 100% rename from doc/srcdoc/Makefile rename to doc/Makefile diff --git a/doc/demo_syntax.md b/doc/demo_syntax.md deleted file mode 100644 index 3ec05e6..0000000 --- a/doc/demo_syntax.md +++ /dev/null @@ -1,315 +0,0 @@ -## A SECoP Syntax for Demonstration - -I feel it is very hard to explain in a talk what we are talking -about when discussing the concepts of SECoP. Would it not be easier -with an example syntax and an example SEC node? That is why I -created a simple syntax, which is on one hand easily understandable -by humans and on the other hand fulfills the requirements for a real syntax. - -### An Example of an SEC Node with the Demo Syntax - -We have 2 main devices: sample temperature and magnetic field. - - > ts - ts=9.887 - - > mf - mf=5.1 - - -We have some additional devices, coil temperature of upper and lower coil. - - > tc1 - tc1=2.23 - - > tc2 - tc2=2.311 - -When we use the term "device" here, we do not mean a device in the sense of a -cryomagnet or a furnace. For SECoP, roughly any physical quantity which may -be of interest to the experimentalist, is its own device. - - -We can use wildcards to see the values of all devices at once. - - > * - ts=9.887 - mf=5.1 - tc1=2.23 - tc2=2.311 - label='Cryomagnet MX15; at 9.887 K; Persistent at 5.1 Tesla' - - -The "> " is not part of the syntax, it is just indicating the request. -A request is always one line. -A reply might contain several lines and always ends with an empty line. - -The last device here is a text displayed on the SE computer. It may not be -very useful, but it demonstrates that a device value may also be a text. - -A device has parameters. The main parameter is its value. The value parameter -is just omitted in the path. We can list the the parameters and its values -with the following command: - - > mf:* - mf=5.13 - mf:status=0 - mf:target=14.9 - mf:ramp=0.4 - mf:set_point=5.13 - mf:persistent_mode=0 - mf:switch_heater=1 - -If we want to change the field we have to set its target value: - - > mf:target=12 - mf:target=12.0 - - > mf:* - mf=5.13 - mf:status=1 - mf:target=12.0 - mf:ramp=0.4 - mf:set_point=5.13 - mf:persistent_mode=0 - mf:switch_heater=1 - -The status is indicating the state of the device. 0 means idle, 1 means busy -(running to the target). - -A parameter has properties. The 'value' property is implicit, its just -omitted in the path: - - > mf:status:* - mf:status=0 - mf:status:value_names=0:idle,1:busy,2:error - mf:status:type=int - mf:status:t=2016-08-23 14:55:45.254348 - -Please notice the property "value_names" indicating the meaning of the status -values. - - > mf:target:* - mf:target=12.0 - mf:target:writable=1 - mf:target:unit=T - mf:target:type=float - mf:target:t=2016-08-23 14:55:44.658749 - -The last property 't' is the timestamp. If the client want to record timestamps, -it can enable it for all device or parameter readings: - - > :reply_items=t - :reply_items=t - - > * - ts=9.867;t=2016-08-23 14:55:44.655862 - mf=5.13;t=2016-08-23 14:55:44.656032 - tc1=2.23;t=2016-08-23 14:55:44.656112 - tc2=2.311;t=2016-08-23 14:55:44.656147 - label='Cryomagnet MX15; at 9.867 K; Ramping at 5.13 Tesla';t=2016-08-23 14:55:44.656183 - -There is also a list command showing the devices (and parameters) without -values. I am not sure if we really need that, as we can just use a wildcard -read command and throw away the values. - - > !* - ts - mf - tc1 - tc2 - label - - > !ts:* - ts - ts:status - ts:target - ts:ramp - ts:use_ramp - ts:set_point - ts:heater_power - ts:raw_sensor - -The property "meaning" indicates the meaning of the most important devices. -We can list all the devices which have a "meaning" property - - > *::meaning - ts::meaning=temperature - mf::meaning=magnetic_field - -> Markus: We have more things to tell here. - - -As a last example: the ultimate command to get everything: - - > *:*:* - ts=9.887 - ts::meaning=temperature - ts::unit=K - ts::description='VTI sensor (15 Tesla magnet)\ncalibration: X28611' - ts::type=float - ts::t=2016-08-23 14:55:44.655862 - ts:status=0 - ts:status:type=int - ts:status:t=2016-08-23 14:55:44.655946 - ts:target=10.0 - ts:target:writable=1 - ts:target:unit=K - ts:target:type=float - ts:target:t=2016-08-23 14:55:44.655959 - ts:ramp=0.0 - ts:ramp:writable=1 - ts:ramp:unit=K/min - ts:ramp:type=float - ts:ramp:t=2016-08-23 14:55:44.655972 - ts:use_ramp=0 - ts:use_ramp:type=int - ts:use_ramp:t=2016-08-23 14:55:44.655984 - ts:set_point=10.0 - ts:set_point:unit=K - ts:set_point:type=float - ts:set_point:t=2016-08-23 14:55:44.655995 - ts:heater_power=0.154 - ts:heater_power:unit=W - ts:heater_power:type=float - ts:heater_power:t=2016-08-23 14:55:44.656006 - ts:raw_sensor=1876.3 - ts:raw_sensor:unit=Ohm - ts:raw_sensor:type=float - ts:raw_sensor:t=2016-08-23 14:55:44.656018 - mf=5.13 - mf::meaning=magnetic_field - mf::unit=T - mf::description=magnetic field (15 Tesla magnet) - mf::type=float - mf::t=2016-08-23 14:55:44.656032 - mf:status=0 - mf:status:type=int - mf:status:t=2016-08-23 14:55:44.656044 - mf:target=12.0 - mf:target:writable=1 - mf:target:unit=T - mf:target:type=float - mf:target:t=2016-08-23 14:55:44.658749 - mf:ramp=0.4 - mf:ramp:writable=1 - mf:ramp:unit=T/min - mf:ramp:type=float - mf:ramp:t=2016-08-23 14:55:44.656066 - mf:set_point=5.13 - mf:set_point:unit=T - mf:set_point:type=float - mf:set_point:t=2016-08-23 14:55:44.656077 - mf:persistent_mode=0 - mf:persistent_mode:type=int - mf:persistent_mode:t=2016-08-23 14:55:44.656088 - mf:switch_heater=1 - mf:switch_heater:type=int - mf:switch_heater:t=2016-08-23 14:55:44.656099 - tc1=2.23 - tc1::unit=K - tc1::description='top coil (15 Tesla magnet)\ncalibration: X30906' - tc1::type=float - tc1::t=2016-08-23 14:55:44.656112 - tc1:status=0 - tc1:status:type=int - tc1:status:t=2016-08-23 14:55:44.656123 - tc1:raw_sensor=5434.0 - tc1:raw_sensor:unit=Ohm - tc1:raw_sensor:type=float - tc1:raw_sensor:t=2016-08-23 14:55:44.656134 - tc2=2.311 - tc2::unit=K - tc2::description='bottom coil (15 Tesla magnet)\ncalibration: C103' - tc2::type=float - tc2::t=2016-08-23 14:55:44.656147 - tc2:status=0 - tc2:status:type=int - tc2:status:t=2016-08-23 14:55:44.656159 - tc2:raw_sensor=4834.5 - tc2:raw_sensor:unit=Ohm - tc2:raw_sensor:type=float - tc2:raw_sensor:t=2016-08-23 14:55:44.656169 - label='Cryomagnet MX15; Ramping' - label::writable=1 - label::type=string - label::t=2016-08-23 14:55:44.656183 - .:reply_items=t - .:reply_items:writable=1 - .:reply_items:type=string - .:reply_items:t=2016-08-23 14:55:44.659617 - .:compact_output=0 - .:compact_output:writable=1 - .:compact_output:type=int - .:compact_output:t=2016-08-23 14:55:44.656219 - - -The last device '.' is a dummy device to hold the parameters of a client -connection. Changing these parameters must not affect other client connections. -The experimental parameter compact_output is for compressing the result of -wildcard requests: unchanged device and parameter names are omitted. - - - > :compact_output=1 - .:compact_output=1 - - > *:*:* - ts=9.887 - ::meaning=temperature - ::unit=K - ::description='VTI sensor (15 Tesla magnet)\ncalibration: X28611' - ::type=float - ::t=2016-08-23 15:04:55.180514 - :status=0 - ::type=int - ::t=2016-08-23 15:04:55.180587 - :target=10.0 - ::writable=1 - ::unit=K - ::type=float - ::t=2016-08-23 15:04:55.180594 - :ramp=0.0 - ::writable=1 - ::unit=K/min - ::type=float - ::t=2016-08-23 15:04:55.180599 - :use_ramp=0 - ::type=int - ::t=2016-08-23 15:04:55.180604 - :set_point=10.0 - ::unit=K - ::type=float - ::t=2016-08-23 15:04:55.180609 - :heater_power=0.154 - ::unit=W - ::type=float - ::t=2016-08-23 15:04:55.180615 - :raw_sensor=1876.3 - ::unit=Ohm - ::type=float - ::t=2016-08-23 15:04:55.180620 - mf=5.13 - ::meaning=magnetic_field - ::unit=T - ::description=magnetic field (15 Tesla magnet) - ::type=float - ::t=2016-08-23 15:04:55.180626 - :status=0 - ::type=int - ::t=2016-08-23 15:04:55.180632 - :target=14.9 - ::writable=1 - ::unit=T - ::type=float - ::t=2016-08-23 15:04:55.180637 - :ramp=0.4 - ::writable=1 - ::unit=T/min - ::type=float - ::t=2016-08-23 15:04:55.180642 - :set_point=5.13 - ::unit=T - - ... - - diff --git a/doc/demo_syntax_mapping.md b/doc/demo_syntax_mapping.md deleted file mode 100644 index 705a87b..0000000 --- a/doc/demo_syntax_mapping.md +++ /dev/null @@ -1,285 +0,0 @@ -## A SECoP Syntax for Demonstration - -### Mapping of Messages - -Please remind: replies always end with en empty line, which means that there are -2 newline characters at the end of each reply. To emphasize that, in this document -a bare '_' is shown as a replacement for the closing empty line. - -#### ListDevices - - > !* - - - ... - - _ - -#### ListDeviceParams - - > !:* - : - : - ... - : - _ - -#### ReadRequest - - > : - := - _ - -Or, in case it is combined with timestamp (may be also sigma, unit ...). See also -below under "client parameters" / "reply_items". - - > : - :=;t= - _ - > : - :=;t=;s= - _ - > : - :=;t=;s=;unit= - _ - -#### ReadPropertiesOfAllDevices -remark: for shortness the name of the value property and the preceding ':' is omitted - - > *:*:* - := - ::= - ... - ::= - _ - -#### ReadPropertiesOfADevice -means read properties of all parameters of a device) - - > :*:* - := - ::= - ... - ::= - _ - -#### ReadPropertiesOfAParameter - - > ::* - := - ::= - ... - ::= - _ - -#### ReadSpecificProperty - - > :: - ::= - _ - -In case you want the value only, and not the timestamp etc, '.' is a placeholder for the -value property - - > ::. - ::.= - _ - -#### ReadValueNotOlderThan - -Instead of this special Request, I propose to make a client parameter "max_age", -which specifies in general how old values may be to be returned from cache. - -#### Write - -remark: writes to other than the 'value' property are not allowed. If anyone sees a -reasonable need to make writeable properties, a WriteProperty Request/Reply should -be discussed - - > := - := - _ - -#### Command - -If we want to distinguish between a write request and a command, we need also a -different syntax. It is to decide, how arguments may be structured / typed. -Should a command also send back a "return value"? - - > : - : - _ - -#### Error replies - -Error reply format: - - ~~ - _ - -The error-specifier should be predefined identifer. - - > tempature:target - ~NoSuchCommand~ tempature - _ - - > temperature:taget - ~NoSuchParameter~ temperature:taget - _ - -#### FeatureListRequest - -Instead of an extra FeatureListRequest message, I propose to do have a device, -which contains some SEC node properties, with information about the SEC node, -and client parameters, which can be set by the ECS for optional -features. Remind that internally the SEC Node has to store the client parameters -separately for every client. - -#### SEC Node properties - -You are welcome to propose better names: - - > ::implements_timestamps - ::implements_timestamps=1 - _ - > ::implements_async_communication - ::implements_async_communication=1 - _ - -The maximum time delay for a response from the SEC Node: - - > ::reply_timeout=10 - ::reply_timeout=10 - _ - -SEC Node properties might be omitted for the default behaviour. - -#### Client parameters - -Enable transmission of timestamp and sigma with every value - - > :reply_items=t,s - :reply_items=t,s - _ - -If a requested property is not present on a parameter, it is just omitted in the reply. - -The reply_items parameter might be not be present, when the SEC node does not implement -timestamps and similar. - -Update timeout (see Update message) - - > :update_timeout=10 - :update_timeout=10 - -#### SubscribeToAsyncData - -In different flavors: all parameters and all devices: - - > +*:* - . - ... - . - _ - -Only the values of all devices: - - > +* - + - ... - + - _ - -All parameters of one device: - - > +:* - +: - ... - +: - _ - -I think we need no special subscriptions to properties, as :reply_items should be -recognized by the updates. All other properties are not supposed to be changed during -an experiment (we might discuss this). - -If an Unsubscribe Message would be implemented, it could be start with a '-' - -#### Update - -In order to stick to a strict request / reply mechanism I propose instead of a real -asynchronous communication to have an UpdateRequest. The reply of an UpdateRequest -might happen delayed. - -- it replies immediately with a list of all subscripted updates, if some happend since - the last UpdateRequest -- if nothing has changed, the UpdateReply is sent as soon as any update happens -- if nothing happens within the time specified by :update_timeout - an empty reply is returned. - -If a client detects no reply within :update_timeout plus ::reply_timeout, -it can assume the the SEC Node is dead. - -The UpdateRequest may be just an empty line (my favorite) or, if you prefer an -question mark: - - > ? - = - .= - _ - -With no update during :update_timeout seconds, the reply would be - - > ? - _ - - -#### Additional Messages - -I list here some additional messages, which could be useful, but wich were not yet -identified as special messages. They all follow the same syntax, which means that -it is probably no extra effort for the implementation. - -Interestingly, we have defined ReadPropertiesOfAllDevices, but not Read a specific -property of all parameters. At least reading the value properties is useful: - - > *:* - -List all device classes (assuming a device property "class") - - > *::class - ::class= - ::class= - ... - ::class= - _ - -The property meaning is for saying: this device is important for the experimentalist, -and has the indicated meaning. It might be used by the ECS to skip devices, which -are of no interest for non experts. Example: - - > *::meaning - ts::meaning=sample temperature - mf::meaning=magnetic field - _ - -We might find other useful messages, which can be implemented without any additional -syntax. - - -#### A possible syntax extension: - -Allow a comma separated list for path items: - - > ts,mf - ts=1.65 - mf=5.13 - _ - - > ts::.,t,s - ts= - ts::t= - ts::s= - _ - -If somebody does not like the :reply_items mechanism, we could us the latter example -as alternative for reading values together with timestamp and sigma. diff --git a/doc/srcdoc/make.bat b/doc/make.bat similarity index 100% rename from doc/srcdoc/make.bat rename to doc/make.bat diff --git a/doc/messages.md b/doc/messages.md deleted file mode 100644 index a0bbaaa..0000000 --- a/doc/messages.md +++ /dev/null @@ -1,279 +0,0 @@ - -(Outdated!) - -Struktur der Messages -===================== - -Es gibt folgende Messagetypen: - - * LIST (listet namen einer Ebene auf) - * READ+WRITE (addressiert einen spezifischen Wert) - * FETCH (kombiniert LIST+READ, antwort ist multi) - * COMMAND (um Befehle aufzurufen: stop(), init(),...) - * (UN)SUBSCRIBE (bucht events, bestellt sie ab, für devices/params) - * EVENT (ASYNC!) - * ERROR - * POLL (wie FETCH, aber fragt vorher die HW, kann dauern) - * TRIGGER (Wie POLL, aber die Antworten kommen als Events, return sofort) - -Außer EVENT und ERROR (beides nur als Reply) gibts es jede Message als Request und als Reply. -Das Parsing einer Message ist eindeutig, so hat jeder reply mindestens ein '=', jede Mehrfachantwort endet mit '`#`', uswusf. -Für das Parsing wird eine Regexp empfohlen, da die syntax nicht sonderlich parsingfreundlich ist. - -Um auszuwählen, auf welche Objekte eine Nachricht wirkt, werden folgende Argumente verwendet: - - - `*` wirkt auf alle devices - - `device` wirkt auf das Device - - `device:*` wirkt auf alle parameter des gegebenen devices - - `device:param` wirkt auf den Parameter des Device - - `device:param:*` wirkt auf alle properties des gegebenen parameters - - `device:param:property` wirkt auf die property - -Properties sind immer ReadOnly Softwarewerte. Somit haben WRITE, TRIGGER, (UN)SUBSCRIBE auf properties keinen sinn und sind mit einem Error zu beantworten. -(welcher? ProtokollError?= - -Replies enthalten immer genau eine Antwort. -Der immer anzugebende 'Antwortwert' wird durch `=` von einer kopie des requestes abgetrennt. -Für Multi-Antworten endet die Antwort in `#\n` statt in `\n`. -Hier ist kein '=' zusätzlich anzugeben. Nach dieser 'Eröffnungsnachricht' kommen die angegebene Anzahl Antworten als Read-Replies. - -Damit ergeben sich folgende Kombinationen (immer zuerst der Request, direkt drunter der Reply, direkt drunter die Beschreibung): -Danach die 'dringlichkeit des implementierens': -MANDATORY > RECOMMENDED > OPTIONAL - -Werte sind entweder Zahlen (`1.23`) oder Strings (`"Ein String"` oder `Text`). -Solange eindeutigkeit besteht (kein '" ", ",", oder " im String) können die `"` weggelassen werden. Beispiel: unit=T - - -LIST ----- - - * 'LIST *' oder 'LIST' - * 'LIST *=mf,tc1,tc1,ts,...' oder 'LIST=mf,tc1,...' - * ListDevices: returns ',' separated list of devicenames - * MANDATORY - ---------------- - - * 'LIST ``' - * 'LIST ``=status, target, value,...' - * ListParameters: returns ',' separated list of parameternames for a device - * MANDATORY - ---------------- - - * 'LIST `:`' - * 'LIST `:`=timestamp, unit, description,...' - * ListProperties: returns ',' separated list of propertynames for a parameter - * MANDATORY - - -READ/WRITE ----------- - - * 'READ ``' - * 'READ `=; [ '=' ';']`' - * ReadDevice: returns current device value + qualifiers - * MANDATORY - ---------- - - * 'READ `:`' - * 'READ `:=; [ '=' ';']`' - * ReadParameter: returns current parameter value (+ qualifiers?) - * MANDATORY - --------- - - * 'READ `::`' - * 'READ `::=;`' - * ReadProperty: returns curent value of property - * RECOMMENDED - --------- - - * 'WRITE `=`' - * 'WRITE `==; [ '=' ';']`' - * WriteDevice: sets new device-value and returns read-back target value + non-empty qualifiers! (at least the `;` must be present) - * MANDATORY - --------- - - * 'WRITE `:=`' - * 'WRITE `:==; [ '=' ';']`' - * WriteParameter: sets new parameter-value and returns read-back value + non-empty qualifiers! (at least the `;` must be present) - * MANDATORY - - -COMMAND -------- - - * 'COMMAND `:'(' [ ','] ')'`' - * 'COMMAND `:'(' [ ','] ')=' result`;' - * ExecuteCommand: führt command mit den gegebenen Arguments aus. - result=(ein) Rückgabewert, kann auch "OK" sein, falls kein Rückgabewert definiert wurde. - * MANDATORY - -commands sind parameter deren name auf '()' endet. -(oder die argumenttypen in () enthält?) - -(UN)SUBSCRIBE -------------- - - * 'SUBSCRIBE ``' - * 'SUBSCRIBE `=OK`;' - * SubscribeDevice: subscribed auf den devicevalue (evtl auch auf den status?) - * RECOMMENDED - * possible extension: include a 'FETCH ``' reply as Multi - --------- - - * 'SUBSCRIBE ``' - * 'SUBSCRIBE `=`;' - * SubscribeALLParameter: subscribed alle parameter eines device - * RECOMMENDED - * possible extension: include a 'FETCH `:`' reply as Multi - --------- - - * 'SUBSCRIBE `:`' - * 'SUBSCRIBE `:=OK`;' - * SubscribeParameter: subscribed auf den parameter - * RECOMMENDED - * possible extension: include a 'FETCH `:`' reply as Multi - --------- - - * 'UNSUBSCRIBE ``' - * 'UNSUBSCRIBE `=OK`;' - * UNSubscribeDevice: unsubscribed auf den devicevalue - * RECOMMENDED - * possible extension: return list of remaining subscriptions as multi - --------- - - * 'UNSUBSCRIBE `:`' - * 'UNSUBSCRIBE `:=OK`;' - * UNSubscribeALLParameter: unsubscribed alle parameter eines device - * RECOMMENDED - * possible extension: return list of remaining subscriptions as multi - --------- - - * 'UNSUBSCRIBE `:`' - * 'UNSUBSCRIBE `:=OK`;' - * UNSubscribeParameter: unsubscribed auf den parameter - * RECOMMENDED - * possible extension: return list of remaining subscriptions as multi - -Was ist zu tun bei einem unsubscribe auf einen nicht subscribten wert? -(doppeltes unsubscribe nach subscribe, etc...) - -EVENT ------ - - * EVENT gibt es nicht als Request, da es nur als async reply auftaucht - * '`#3\n`EVENT READ `mf=1.2\n`EVENT READ `mf:target=2.0\n`EVENT READ `mf:status="BUSY"\n`' - * Event: sendet ein subscribed event, kann 0..N READ-replies beinhalten - * RECOMMENDED - -FETCH/POLL ----------- - - * 'FETCH :' oder 'FETCH' - * 'FETCH `:#2\nREAD mf=1.2\nREAD ts=3.4\n`' oder 'FETCH`#2\nREAD mf=1.2\nREAD ts=3.4\n`' - * FetchDevices: reads and returns the values of all (interesting?) devices - * OPTIONAL - --------- - - * 'FETCH ``' - * 'FETCH mf#2\nREAD mf:value=1.2\nREAD mf:status="IDLE"\n`' - * FetchDevice: reads and returns the (interesting?) parameters of a device - * OPTIONAL - --------- - - * 'FETCH `:`' - * 'FETCH `mf:#3\nREAD mf:value=1.2\nREAD mf:target=1.2\nREAD mf:status="IDLE"\n`' - * FetchParameters: reads and returns the values of all parameters of a device - * OPTIONAL - --------- - - * 'FETCH `:`' - * 'FETCH `mf:value#2\nREAD mf:value:unit="T"\nREAD mf:value:type=float\n`' - * FetchParameter: reads and returns the properties of a single parameter - * OPTIONAL - --------- - - * 'FETCH `::`' - * 'FETCH `mf:value:#2\nREAD mf:value:unit="T"\nREAD mf:value:type=float\n`' - * FetchProperties: reads and returns the values of all properties of a parameter - * OPTIONAL - -POLL wird wie FETCH kodiert, fragt aber die HW vor der Antwort, FECTH liefert zwischengespeicherte Werte. - -TRIGGER -------- - - * 'TRIGGER :' oder 'TRIGGER' - * 'TRIGGER :=OK' oder 'TRIGGER=OK' - * TriggerDeviceReads: startet auslesen aller devices und übertragen der (subscribed) values als events - * OPTIONAL - --------- - - * 'TRIGGER ``' - * 'TRIGGER `mf=OK`' - * TriggerDeviceRead: startet auslesen eines Devices - * OPTIONAL - --------- - - * 'TRIGGER `:`' - * 'TRIGGER `mf:=OK`' - * TriggerParameterReads: startet auslesen aller paremeter und übertragen der subscribed parameter als events - * OPTIONAL - --------- - - * 'TRIGGER `:`' - * 'TRIGGER `mf:value=OK`' - * FetchProperties: reads and returns the values of all properties of a parameter - * OPTIONAL - -ERROR ------ - - * ERROR gibt es nicht als request, da es nur als reply auftaucht - * 'ERROR ` "" []`' - * Error: zeigt einen Fehler an. folgende sind definiert: - * NoSuchDevice - * NoSuchParameter - * NoSuchCommand - * NoSuchProperty - * CommandFailed - * ReadOnly - * BadValue - * CommunicationFailed - * IsBusy - * IsError - * ProtocolError - * SyntaxError - * MANDATORY - - -Möglich Erweiterung: für device/param/property kann statt eines einzelnamens auch eine ',' separierte Liste verwendet werden. -Außerdem könnte auch ein '*' für 'ALLE' stehen. -Die Antworten sind dann auf jeden Fall als Multi zu kodieren. Beispiel: - - > READ mf:target,value - > > READ mf:target,value#2 - > - > > READ mf:target=1.23 - > - > > READ mf:value=0.73 - > - diff --git a/doc/notes.md b/doc/notes.md deleted file mode 100644 index 384de7d..0000000 --- a/doc/notes.md +++ /dev/null @@ -1,39 +0,0 @@ ------- -No installation required or recommended. ------ - -everything runs directly from the checkout. - -you need: - - python2.7.* - - pip - - linux OS (Mac may work as well) - -install requirements with pip: -$ sudo pip install -r requirements.txt - -to execute a program, prefix its name with bin/, e.g.: -$ bin/make_doc.py -$ bin/server.py start test - -a testsuite is planned but nothing is there yet. - -## structure ## - - * bin contains the executables (make_doc.py, server.py) - * doc is the root node of the docu (see index.md) - * etc contains the configurations for the server(s) and devices - * html contains the docu after make_doc.py was run - * log contains some (hopefully) log output from the servers - * pid contains pidfiles if a server is running - * src contains the python source - * src/client: client specific stuff (proxy) - * src/devices: devices to be used by the server (and exported via SECoP) - * src/lib: helper stuff (startup, pidfiles, etc) - * src/protocol: protocol specific stuff - * src/errors.py: internal errors - * src/server.py: device-managing part of the server (transport is in src/protocol/transport) - * src/validators.py: validators used by the devices. may be moved to src/protocol - -# THERE IS STILL MUCH WORK TO DO! # - diff --git a/doc/protocols/simple_communication_protocol.rst b/doc/protocols/simple_communication_protocol.rst deleted file mode 100644 index 56a1cfd..0000000 --- a/doc/protocols/simple_communication_protocol.rst +++ /dev/null @@ -1,372 +0,0 @@ -Simple communication protocol -============================= -| *Version 0.0.2* -| *Copyright 2012: Alexander Lenz, Dr. Enrico Faulhaber* - - -Table of contents ------------------ - -.. contents:: -.. sectnum:: - -Disambiguation --------------- - -Device -'''''' -A device is a logical part of the complete system. This may be any piece of hardware which -can be accessed seperately. Also a logical axis, implemented with multiple motors can be a device. - -Parameter -''''''''' -A parameter is a device depended value which represents (usually) a physical value. -It can be read only or read-/writeable. - -Messages --------- - -The messages are devided into commands and responses. - -A command consists of the device of interest, the relevant parameter, an operator -that specifies what should happen, and a value if neccessary. - -:: - - Commands: /\n - -You will get a response for each command (\ **even if it failed!**\ ). -These reponses consist of an error code, the mirrored command (to verify for what command the response is related) -and a value if requested. - -:: - - Response: \n - - -For limitations regarding the message contents, have a look at: `Limitations`_ - - - -Operators ---------- - -? (Request) -''''''''''' - This operator can be used to request data. - In the most cases, you want to request the value of device parameter: - - **Command** - :: - - /?\n - - **Response** - :: - - /=\n - -= (Set) -''''''' - This operator can be used to write a device value. - - **Command** - :: - - /=\n - - **Response** - :: - - /=\n - - -Protocol error codes --------------------- - -In case of an error, you get the following response: - -:: - - - - -The following errors describe errors of the protocol, not the device. - -======================= ============== -**Error** **Error code** -======================= ============== -No error 0 -Unknown error 1 -Connection error 2 -Command unknown 3 -Device unknown 4 -Parameter unknown 5 -Format error 6 -Value out of limits 7 -Param not writable 8 -Not allowed 9 -======================= ============== - -Device stati ------------- - -The following status codes describe the device status and can be requested via: - -:: - - /status:\n - - -========== =========== -**Status** **Meaning** -========== =========== -IDLE Device is alive and ready to accept commands. -BUSY Device is performing some action and therefore busy. It doesn't accept new commands. All Parameters can be read. -ERROR Something bad happened, a manual action is required. Some command could unexpectedly not be performed. -UNKNOWN Unknown device state. -========== =========== - - -Limitations ------------ - -Naming & Formatting -''''''''''''''''''' - -- Device names are all lower case and can consist of letters, numbers and underscores (no whitespace!). -- Device names consist of up to 80 characters. -- Parameter names are all lower case and can consist of letters, numbers and underscores (no whitespace!). -- Parameter names consist of up to 80 characters. -- Floating point numbers are using a decimal point (5.23). -- Lists are commma-separated and enclosed by square brackets ([entry1,entry2,entry3]). -- Strings are enclosed by single ticks ('str'). -- Messages consist of up to 256 characters. - -Devices -''''''' - -General -""""""" -All devices have to support at least the following parameters: - - **status** - This **read only** parameters describes the current device state. - It contains a list with two items. - - 1. A short constant status string (Have a look at: `Device stati`_) - 2. A longer description which can contain any character except a comma! - - **parameters** - This **read only** parameter represents a list of all available parameters of the given device. - It contains a comma seperated list with all parameter names. - -Readable -"""""""" -All devices which provide any type of readable value have to support the general parameters and at leas the following: - **value** - This **read only** parameter represents the current 'main value'. - It contains a single value which can be a float or integer number, or a string. - -Writable -"""""""" -All devices for which you can set a value have to support at least the general parameters, all parameters of `Readable`_ devices and the following: - **target** - This **read/write** parameter represents the device's target value. - It contains a single value which can be a float or integer number, or a string. - If you set the target value, the device goes into 'BUSY' state and tries to reach that value. - The current value can be requested by the 'value' parameter. - -Server device -""""""""""""" - The server have to provide a device for direct communication with the protocol server. - It has to provide at least the parameters of a general device (`Devices`_) plus the following: - - **devices** - A list of all available devices. - **version** - A version string which identifies the protocol version, the server implements. - - The server device can be queried by omitting the parameter (+ the '/'). - :: - - devices?\n - version?\n - - -Examples --------- - -Let's have a look at some examples: - -+---------------+---------------------------------+ -|**Device:** |temp_ctrl | -+---------------+---------------------------------+ -|**Type:** |Temperature controller (Moveable)| -+---------------+---------------------------------+ -|**Parameters:**| - status **(mandatory)** | -| | - parameters **(mandatory)** | -| | - value **(mandatory)** | -| | - target **(mandatory)** | -| | - ... | -+---------------+---------------------------------+ - -Requesting the current setpoint (target) -'''''''''''''''''''''''''''''''''''''''' - - **Command** - - :: - - temp_ctrl/target?\n - - **Response** - - :: - - 0 temp_ctrl/target=0.42\n - -Setting the setpoint (target) -''''''''''''''''''''''''''''' - - **Command** - - :: - - temp_ctrl/target=0.21\n - - **Response** - - :: - - 0 temp_ctrl/target=0.21\n - -Setting an out-of-bounds setpoint (target) -'''''''''''''''''''''''''''''''''''''''''' - - **Command** - - :: - - temp_ctrl/target=-7.5\n - - **Response** - - :: - - 7 temp_ctrl/target=-7.5\n - - -Requesting the status -''''''''''''''''''''' - - **Command** - - :: - - temp_ctrl/status?\n - - **Response** - - :: - - 0 temp_ctrl/status=BUSY,I'm ramping!\n - -Requesting the device list -'''''''''''''''''''''''''' - - **Command** - - :: - - /devices?\n - - **Response** - - :: - - 0 /devices=temp_ctrl,another_dev1,another_dev2\n - -.. Allowed extensions - ------------------ - - Additional operators - '''''''''''''''''''' - - \* (Wildcard) - """"""""""""" - This operator is a little more advanced than the others. - It represents a wild card and can be combined with other operators. - The response you will get, are multiple messages which contain: - :: - - - - If you want to request all parameters of a device, it will be: - - **Command** - :: - - /*?\n - - **Response** - *Multiple* - :: - - /*? /=\n - - Examples - ^^^^^^^^ - Requesting all parameters - ************************* - - **Command** - - :: - - temp_ctrl/*?\n - - **Response** - :: - - 0 temp_ctrl/*? temp_ctrl/status=BUSY,I'm ramping!\n - 0 temp_ctrl/*? temp_ctrl/parameters=status,parameters,value,target\n - 0 temp_ctrl/*? temp_ctrl/value=0.21\n - 0 temp_ctrl/*? temp_ctrl/target=0.42\n - -Recommendations ---------------- -Interfaces -'''''''''' - -We provide some recommendations for the interface configuration when using the simple communication protocol: - -Serial (RS232) -"""""""""""""" - -If you are using a serial connection, you should use the following configuration: - -============= ============== -**Baudrate** 9600 or 115200 -**Data bits** 8 -**Parity** None -**Stop bits** 1 -============= ============== - -Network (TCP) -""""""""""""" - -If you are using a TCP based network connection, you should use the following configuration: - -======== ===== -**Port** 14728 -======== ===== - -Network (UDP) -""""""""""""" - -We recommend not to use UDP connections at all, as the protocol was not designed for such connections. - - - - diff --git a/doc/srcdoc/source/conf.py b/doc/source/conf.py similarity index 99% rename from doc/srcdoc/source/conf.py rename to doc/source/conf.py index f792acf..3dd36b1 100644 --- a/doc/srcdoc/source/conf.py +++ b/doc/source/conf.py @@ -22,7 +22,7 @@ from os import path # sys.path.insert(0, os.path.abspath('.')) # Add import path for inplace usage -sys.path.insert(0, path.abspath(path.join(path.dirname(__file__), '..', '..', '..'))) +sys.path.insert(0, path.abspath(path.join(path.dirname(__file__), '..', '..'))) from secop.version import get_version diff --git a/doc/srcdoc/source/index.rst b/doc/source/index.rst similarity index 100% rename from doc/srcdoc/source/index.rst rename to doc/source/index.rst diff --git a/doc/srcdoc/source/playground/client/index.rst b/doc/source/playground/client/index.rst similarity index 100% rename from doc/srcdoc/source/playground/client/index.rst rename to doc/source/playground/client/index.rst diff --git a/doc/srcdoc/source/playground/facility/demo/cryo.rst b/doc/source/playground/facility/demo/cryo.rst similarity index 100% rename from doc/srcdoc/source/playground/facility/demo/cryo.rst rename to doc/source/playground/facility/demo/cryo.rst diff --git a/doc/srcdoc/source/playground/facility/demo/index.rst b/doc/source/playground/facility/demo/index.rst similarity index 100% rename from doc/srcdoc/source/playground/facility/demo/index.rst rename to doc/source/playground/facility/demo/index.rst diff --git a/doc/srcdoc/source/playground/facility/demo/test.rst b/doc/source/playground/facility/demo/test.rst similarity index 100% rename from doc/srcdoc/source/playground/facility/demo/test.rst rename to doc/source/playground/facility/demo/test.rst diff --git a/doc/srcdoc/source/playground/facility/ess/epics.rst b/doc/source/playground/facility/ess/epics.rst similarity index 100% rename from doc/srcdoc/source/playground/facility/ess/epics.rst rename to doc/source/playground/facility/ess/epics.rst diff --git a/doc/srcdoc/source/playground/facility/ess/index.rst b/doc/source/playground/facility/ess/index.rst similarity index 100% rename from doc/srcdoc/source/playground/facility/ess/index.rst rename to doc/source/playground/facility/ess/index.rst diff --git a/doc/srcdoc/source/playground/facility/index.rst b/doc/source/playground/facility/index.rst similarity index 100% rename from doc/srcdoc/source/playground/facility/index.rst rename to doc/source/playground/facility/index.rst diff --git a/doc/srcdoc/source/playground/facility/mlz/amagnet.rst b/doc/source/playground/facility/mlz/amagnet.rst similarity index 100% rename from doc/srcdoc/source/playground/facility/mlz/amagnet.rst rename to doc/source/playground/facility/mlz/amagnet.rst diff --git a/doc/srcdoc/source/playground/facility/mlz/entangle.rst b/doc/source/playground/facility/mlz/entangle.rst similarity index 100% rename from doc/srcdoc/source/playground/facility/mlz/entangle.rst rename to doc/source/playground/facility/mlz/entangle.rst diff --git a/doc/srcdoc/source/playground/facility/mlz/index.rst b/doc/source/playground/facility/mlz/index.rst similarity index 100% rename from doc/srcdoc/source/playground/facility/mlz/index.rst rename to doc/source/playground/facility/mlz/index.rst diff --git a/doc/srcdoc/source/playground/framework/datatypes.rst b/doc/source/playground/framework/datatypes.rst similarity index 100% rename from doc/srcdoc/source/playground/framework/datatypes.rst rename to doc/source/playground/framework/datatypes.rst diff --git a/doc/srcdoc/source/playground/framework/errors.rst b/doc/source/playground/framework/errors.rst similarity index 100% rename from doc/srcdoc/source/playground/framework/errors.rst rename to doc/source/playground/framework/errors.rst diff --git a/doc/srcdoc/source/playground/framework/index.rst b/doc/source/playground/framework/index.rst similarity index 100% rename from doc/srcdoc/source/playground/framework/index.rst rename to doc/source/playground/framework/index.rst diff --git a/doc/srcdoc/source/playground/gui/index.rst b/doc/source/playground/gui/index.rst similarity index 100% rename from doc/srcdoc/source/playground/gui/index.rst rename to doc/source/playground/gui/index.rst diff --git a/doc/srcdoc/source/playground/index.rst b/doc/source/playground/index.rst similarity index 100% rename from doc/srcdoc/source/playground/index.rst rename to doc/source/playground/index.rst diff --git a/doc/srcdoc/source/playground/server/configuration.rst b/doc/source/playground/server/configuration.rst similarity index 100% rename from doc/srcdoc/source/playground/server/configuration.rst rename to doc/source/playground/server/configuration.rst diff --git a/doc/srcdoc/source/playground/server/index.rst b/doc/source/playground/server/index.rst similarity index 100% rename from doc/srcdoc/source/playground/server/index.rst rename to doc/source/playground/server/index.rst diff --git a/doc/srcdoc/source/playground/server/modules.rst b/doc/source/playground/server/modules.rst similarity index 100% rename from doc/srcdoc/source/playground/server/modules.rst rename to doc/source/playground/server/modules.rst diff --git a/doc/srcdoc/source/playground/server/protocol/encoding/demo_v2.rst b/doc/source/playground/server/protocol/encoding/demo_v2.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/encoding/demo_v2.rst rename to doc/source/playground/server/protocol/encoding/demo_v2.rst diff --git a/doc/srcdoc/source/playground/server/protocol/encoding/demo_v3.rst b/doc/source/playground/server/protocol/encoding/demo_v3.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/encoding/demo_v3.rst rename to doc/source/playground/server/protocol/encoding/demo_v3.rst diff --git a/doc/srcdoc/source/playground/server/protocol/encoding/demo_v4.rst b/doc/source/playground/server/protocol/encoding/demo_v4.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/encoding/demo_v4.rst rename to doc/source/playground/server/protocol/encoding/demo_v4.rst diff --git a/doc/srcdoc/source/playground/server/protocol/encoding/demo_v5.rst b/doc/source/playground/server/protocol/encoding/demo_v5.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/encoding/demo_v5.rst rename to doc/source/playground/server/protocol/encoding/demo_v5.rst diff --git a/doc/srcdoc/source/playground/server/protocol/encoding/index.rst b/doc/source/playground/server/protocol/encoding/index.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/encoding/index.rst rename to doc/source/playground/server/protocol/encoding/index.rst diff --git a/doc/srcdoc/source/playground/server/protocol/framing/demo.rst b/doc/source/playground/server/protocol/framing/demo.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/framing/demo.rst rename to doc/source/playground/server/protocol/framing/demo.rst diff --git a/doc/srcdoc/source/playground/server/protocol/framing/eol.rst b/doc/source/playground/server/protocol/framing/eol.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/framing/eol.rst rename to doc/source/playground/server/protocol/framing/eol.rst diff --git a/doc/srcdoc/source/playground/server/protocol/framing/index.rst b/doc/source/playground/server/protocol/framing/index.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/framing/index.rst rename to doc/source/playground/server/protocol/framing/index.rst diff --git a/doc/srcdoc/source/playground/server/protocol/framing/null.rst b/doc/source/playground/server/protocol/framing/null.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/framing/null.rst rename to doc/source/playground/server/protocol/framing/null.rst diff --git a/doc/srcdoc/source/playground/server/protocol/framing/rle.rst b/doc/source/playground/server/protocol/framing/rle.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/framing/rle.rst rename to doc/source/playground/server/protocol/framing/rle.rst diff --git a/doc/srcdoc/source/playground/server/protocol/index.rst b/doc/source/playground/server/protocol/index.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/index.rst rename to doc/source/playground/server/protocol/index.rst diff --git a/doc/srcdoc/source/playground/server/protocol/interface/index.rst b/doc/source/playground/server/protocol/interface/index.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/interface/index.rst rename to doc/source/playground/server/protocol/interface/index.rst diff --git a/doc/srcdoc/source/playground/server/protocol/interface/tcp.rst b/doc/source/playground/server/protocol/interface/tcp.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/interface/tcp.rst rename to doc/source/playground/server/protocol/interface/tcp.rst diff --git a/doc/srcdoc/source/playground/server/protocol/interface/zmq.rst b/doc/source/playground/server/protocol/interface/zmq.rst similarity index 100% rename from doc/srcdoc/source/playground/server/protocol/interface/zmq.rst rename to doc/source/playground/server/protocol/interface/zmq.rst diff --git a/doc/srcdoc/source/playground/server/starting.rst b/doc/source/playground/server/starting.rst similarity index 100% rename from doc/srcdoc/source/playground/server/starting.rst rename to doc/source/playground/server/starting.rst diff --git a/doc/srcdoc/source/protocol/descjson.rst b/doc/source/protocol/descjson.rst similarity index 100% rename from doc/srcdoc/source/protocol/descjson.rst rename to doc/source/protocol/descjson.rst diff --git a/doc/srcdoc/source/protocol/descprop.rst b/doc/source/protocol/descprop.rst similarity index 100% rename from doc/srcdoc/source/protocol/descprop.rst rename to doc/source/protocol/descprop.rst diff --git a/doc/srcdoc/source/protocol/heartbeat.rst b/doc/source/protocol/heartbeat.rst similarity index 100% rename from doc/srcdoc/source/protocol/heartbeat.rst rename to doc/source/protocol/heartbeat.rst diff --git a/doc/srcdoc/source/protocol/hierarchy.rst b/doc/source/protocol/hierarchy.rst similarity index 100% rename from doc/srcdoc/source/protocol/hierarchy.rst rename to doc/source/protocol/hierarchy.rst diff --git a/doc/srcdoc/source/protocol/history.rst b/doc/source/protocol/history.rst similarity index 100% rename from doc/srcdoc/source/protocol/history.rst rename to doc/source/protocol/history.rst diff --git a/doc/srcdoc/source/protocol/index.rst b/doc/source/protocol/index.rst similarity index 89% rename from doc/srcdoc/source/protocol/index.rst rename to doc/source/protocol/index.rst index 465ec76..75e45f0 100644 --- a/doc/srcdoc/source/protocol/index.rst +++ b/doc/source/protocol/index.rst @@ -11,7 +11,9 @@ Protocol documentation timeformat modsubset heartbeat + jsonstruct todo + notes history diff --git a/doc/json_structure.md b/doc/source/protocol/jsonstruct.rst similarity index 98% rename from doc/json_structure.md rename to doc/source/protocol/jsonstruct.rst index cd25c94..f3ab408 100644 --- a/doc/json_structure.md +++ b/doc/source/protocol/jsonstruct.rst @@ -1,3 +1,6 @@ +JSON structure +============== + > Mit JSON Freeze meine ich nur Arrays von Objekten also: > -Node hat ein Array von Properties und ein Array von Modulen > -Module haben ein Array von Properties, ein Array von Parametern und ein Array von Commands @@ -18,7 +21,7 @@ property = { 'property-name' : 'property-value' } ODER -==== +---- node = [ , ] diff --git a/doc/srcdoc/source/protocol/messages.rst b/doc/source/protocol/messages.rst similarity index 100% rename from doc/srcdoc/source/protocol/messages.rst rename to doc/source/protocol/messages.rst diff --git a/doc/srcdoc/source/protocol/modsubset.rst b/doc/source/protocol/modsubset.rst similarity index 100% rename from doc/srcdoc/source/protocol/modsubset.rst rename to doc/source/protocol/modsubset.rst diff --git a/doc/source/protocol/notes.rst b/doc/source/protocol/notes.rst new file mode 100644 index 0000000..3ec21ef --- /dev/null +++ b/doc/source/protocol/notes.rst @@ -0,0 +1,42 @@ +Notes +===== + +No installation required or recommended +--------------------------------------- + +everything runs directly from the checkout. + +you need: + - python2.7.* + - pip + - linux OS (Mac may work as well) + +install requirements with pip: +$ sudo pip install -r requirements.txt + +to execute a program, prefix its name with bin/, e.g.: +$ bin/make_doc.py +$ bin/server.py start test + +a testsuite is planned but nothing is there yet. + +Structure +--------- + +* bin contains the executables (make_doc.py, server.py) +* doc is the root node of the docu (see index.md) +* etc contains the configurations for the server(s) and devices +* html contains the docu after make_doc.py was run +* log contains some (hopefully) log output from the servers +* pid contains pidfiles if a server is running +* src contains the python source + + * src/client: client specific stuff (proxy) + * src/devices: devices to be used by the server (and exported via SECoP) + * src/lib: helper stuff (startup, pidfiles, etc) + * src/protocol: protocol specific stuff + * src/errors.py: internal errors + * src/server.py: device-managing part of the server (transport is in src/protocol/transport) + * src/validators.py: validators used by the devices. may be moved to src/protocol + + diff --git a/doc/srcdoc/source/protocol/timeformat.rst b/doc/source/protocol/timeformat.rst similarity index 100% rename from doc/srcdoc/source/protocol/timeformat.rst rename to doc/source/protocol/timeformat.rst diff --git a/doc/srcdoc/source/protocol/todo.rst b/doc/source/protocol/todo.rst similarity index 100% rename from doc/srcdoc/source/protocol/todo.rst rename to doc/source/protocol/todo.rst