Initial Check-in of CLI Library (47b5f8d1) | Commits | arduino / CLI

Browse Code »

Commit 47b5f8d1ea55c2ac10b6e4a1d26a7ab1afd7d18b

Authored by Frederik Lindenaar 6 years ago

0 parents

master

Initial Check-in of CLI Library

Inline Side-by-side

Showing 15 changed files with 2477 additions and 0 deletions

LICENSE.txt 0 → 100644

View file @47b5f8d

	1	+++ a/LICENSE.txt
	1	+ GNU GENERAL PUBLIC LICENSE
	2	+ Version 3, 29 June 2007
	3	+
	4	+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
	5	+ Everyone is permitted to copy and distribute verbatim copies
	6	+ of this license document, but changing it is not allowed.
	7	+
	8	+ Preamble
	9	+
	10	+ The GNU General Public License is a free, copyleft license for
	11	+software and other kinds of works.
	12	+
	13	+ The licenses for most software and other practical works are designed
	14	+to take away your freedom to share and change the works. By contrast,
	15	+the GNU General Public License is intended to guarantee your freedom to
	16	+share and change all versions of a program--to make sure it remains free
	17	+software for all its users. We, the Free Software Foundation, use the
	18	+GNU General Public License for most of our software; it applies also to
	19	+any other work released this way by its authors. You can apply it to
	20	+your programs, too.
	21	+
	22	+ When we speak of free software, we are referring to freedom, not
	23	+price. Our General Public Licenses are designed to make sure that you
	24	+have the freedom to distribute copies of free software (and charge for
	25	+them if you wish), that you receive source code or can get it if you
	26	+want it, that you can change the software or use pieces of it in new
	27	+free programs, and that you know you can do these things.
	28	+
	29	+ To protect your rights, we need to prevent others from denying you
	30	+these rights or asking you to surrender the rights. Therefore, you have
	31	+certain responsibilities if you distribute copies of the software, or if
	32	+you modify it: responsibilities to respect the freedom of others.
	33	+
	34	+ For example, if you distribute copies of such a program, whether
	35	+gratis or for a fee, you must pass on to the recipients the same
	36	+freedoms that you received. You must make sure that they, too, receive
	37	+or can get the source code. And you must show them these terms so they
	38	+know their rights.
	39	+
	40	+ Developers that use the GNU GPL protect your rights with two steps:
	41	+(1) assert copyright on the software, and (2) offer you this License
	42	+giving you legal permission to copy, distribute and/or modify it.
	43	+
	44	+ For the developers' and authors' protection, the GPL clearly explains
	45	+that there is no warranty for this free software. For both users' and
	46	+authors' sake, the GPL requires that modified versions be marked as
	47	+changed, so that their problems will not be attributed erroneously to
	48	+authors of previous versions.
	49	+
	50	+ Some devices are designed to deny users access to install or run
	51	+modified versions of the software inside them, although the manufacturer
	52	+can do so. This is fundamentally incompatible with the aim of
	53	+protecting users' freedom to change the software. The systematic
	54	+pattern of such abuse occurs in the area of products for individuals to
	55	+use, which is precisely where it is most unacceptable. Therefore, we
	56	+have designed this version of the GPL to prohibit the practice for those
	57	+products. If such problems arise substantially in other domains, we
	58	+stand ready to extend this provision to those domains in future versions
	59	+of the GPL, as needed to protect the freedom of users.
	60	+
	61	+ Finally, every program is threatened constantly by software patents.
	62	+States should not allow patents to restrict development and use of
	63	+software on general-purpose computers, but in those that do, we wish to
	64	+avoid the special danger that patents applied to a free program could
	65	+make it effectively proprietary. To prevent this, the GPL assures that
	66	+patents cannot be used to render the program non-free.
	67	+
	68	+ The precise terms and conditions for copying, distribution and
	69	+modification follow.
	70	+
	71	+ TERMS AND CONDITIONS
	72	+
	73	+ 0. Definitions.
	74	+
	75	+ "This License" refers to version 3 of the GNU General Public License.
	76	+
	77	+ "Copyright" also means copyright-like laws that apply to other kinds of
	78	+works, such as semiconductor masks.
	79	+
	80	+ "The Program" refers to any copyrightable work licensed under this
	81	+License. Each licensee is addressed as "you". "Licensees" and
	82	+"recipients" may be individuals or organizations.
	83	+
	84	+ To "modify" a work means to copy from or adapt all or part of the work
	85	+in a fashion requiring copyright permission, other than the making of an
	86	+exact copy. The resulting work is called a "modified version" of the
	87	+earlier work or a work "based on" the earlier work.
	88	+
	89	+ A "covered work" means either the unmodified Program or a work based
	90	+on the Program.
	91	+
	92	+ To "propagate" a work means to do anything with it that, without
	93	+permission, would make you directly or secondarily liable for
	94	+infringement under applicable copyright law, except executing it on a
	95	+computer or modifying a private copy. Propagation includes copying,
	96	+distribution (with or without modification), making available to the
	97	+public, and in some countries other activities as well.
	98	+
	99	+ To "convey" a work means any kind of propagation that enables other
	100	+parties to make or receive copies. Mere interaction with a user through
	101	+a computer network, with no transfer of a copy, is not conveying.
	102	+
	103	+ An interactive user interface displays "Appropriate Legal Notices"
	104	+to the extent that it includes a convenient and prominently visible
	105	+feature that (1) displays an appropriate copyright notice, and (2)
	106	+tells the user that there is no warranty for the work (except to the
	107	+extent that warranties are provided), that licensees may convey the
	108	+work under this License, and how to view a copy of this License. If
	109	+the interface presents a list of user commands or options, such as a
	110	+menu, a prominent item in the list meets this criterion.
	111	+
	112	+ 1. Source Code.
	113	+
	114	+ The "source code" for a work means the preferred form of the work
	115	+for making modifications to it. "Object code" means any non-source
	116	+form of a work.
	117	+
	118	+ A "Standard Interface" means an interface that either is an official
	119	+standard defined by a recognized standards body, or, in the case of
	120	+interfaces specified for a particular programming language, one that
	121	+is widely used among developers working in that language.
	122	+
	123	+ The "System Libraries" of an executable work include anything, other
	124	+than the work as a whole, that (a) is included in the normal form of
	125	+packaging a Major Component, but which is not part of that Major
	126	+Component, and (b) serves only to enable use of the work with that
	127	+Major Component, or to implement a Standard Interface for which an
	128	+implementation is available to the public in source code form. A
	129	+"Major Component", in this context, means a major essential component
	130	+(kernel, window system, and so on) of the specific operating system
	131	+(if any) on which the executable work runs, or a compiler used to
	132	+produce the work, or an object code interpreter used to run it.
	133	+
	134	+ The "Corresponding Source" for a work in object code form means all
	135	+the source code needed to generate, install, and (for an executable
	136	+work) run the object code and to modify the work, including scripts to
	137	+control those activities. However, it does not include the work's
	138	+System Libraries, or general-purpose tools or generally available free
	139	+programs which are used unmodified in performing those activities but
	140	+which are not part of the work. For example, Corresponding Source
	141	+includes interface definition files associated with source files for
	142	+the work, and the source code for shared libraries and dynamically
	143	+linked subprograms that the work is specifically designed to require,
	144	+such as by intimate data communication or control flow between those
	145	+subprograms and other parts of the work.
	146	+
	147	+ The Corresponding Source need not include anything that users
	148	+can regenerate automatically from other parts of the Corresponding
	149	+Source.
	150	+
	151	+ The Corresponding Source for a work in source code form is that
	152	+same work.
	153	+
	154	+ 2. Basic Permissions.
	155	+
	156	+ All rights granted under this License are granted for the term of
	157	+copyright on the Program, and are irrevocable provided the stated
	158	+conditions are met. This License explicitly affirms your unlimited
	159	+permission to run the unmodified Program. The output from running a
	160	+covered work is covered by this License only if the output, given its
	161	+content, constitutes a covered work. This License acknowledges your
	162	+rights of fair use or other equivalent, as provided by copyright law.
	163	+
	164	+ You may make, run and propagate covered works that you do not
	165	+convey, without conditions so long as your license otherwise remains
	166	+in force. You may convey covered works to others for the sole purpose
	167	+of having them make modifications exclusively for you, or provide you
	168	+with facilities for running those works, provided that you comply with
	169	+the terms of this License in conveying all material for which you do
	170	+not control copyright. Those thus making or running the covered works
	171	+for you must do so exclusively on your behalf, under your direction
	172	+and control, on terms that prohibit them from making any copies of
	173	+your copyrighted material outside their relationship with you.
	174	+
	175	+ Conveying under any other circumstances is permitted solely under
	176	+the conditions stated below. Sublicensing is not allowed; section 10
	177	+makes it unnecessary.
	178	+
	179	+ 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
	180	+
	181	+ No covered work shall be deemed part of an effective technological
	182	+measure under any applicable law fulfilling obligations under article
	183	+11 of the WIPO copyright treaty adopted on 20 December 1996, or
	184	+similar laws prohibiting or restricting circumvention of such
	185	+measures.
	186	+
	187	+ When you convey a covered work, you waive any legal power to forbid
	188	+circumvention of technological measures to the extent such circumvention
	189	+is effected by exercising rights under this License with respect to
	190	+the covered work, and you disclaim any intention to limit operation or
	191	+modification of the work as a means of enforcing, against the work's
	192	+users, your or third parties' legal rights to forbid circumvention of
	193	+technological measures.
	194	+
	195	+ 4. Conveying Verbatim Copies.
	196	+
	197	+ You may convey verbatim copies of the Program's source code as you
	198	+receive it, in any medium, provided that you conspicuously and
	199	+appropriately publish on each copy an appropriate copyright notice;
	200	+keep intact all notices stating that this License and any
	201	+non-permissive terms added in accord with section 7 apply to the code;
	202	+keep intact all notices of the absence of any warranty; and give all
	203	+recipients a copy of this License along with the Program.
	204	+
	205	+ You may charge any price or no price for each copy that you convey,
	206	+and you may offer support or warranty protection for a fee.
	207	+
	208	+ 5. Conveying Modified Source Versions.
	209	+
	210	+ You may convey a work based on the Program, or the modifications to
	211	+produce it from the Program, in the form of source code under the
	212	+terms of section 4, provided that you also meet all of these conditions:
	213	+
	214	+ a) The work must carry prominent notices stating that you modified
	215	+ it, and giving a relevant date.
	216	+
	217	+ b) The work must carry prominent notices stating that it is
	218	+ released under this License and any conditions added under section
	219	+ 7. This requirement modifies the requirement in section 4 to
	220	+ "keep intact all notices".
	221	+
	222	+ c) You must license the entire work, as a whole, under this
	223	+ License to anyone who comes into possession of a copy. This
	224	+ License will therefore apply, along with any applicable section 7
	225	+ additional terms, to the whole of the work, and all its parts,
	226	+ regardless of how they are packaged. This License gives no
	227	+ permission to license the work in any other way, but it does not
	228	+ invalidate such permission if you have separately received it.
	229	+
	230	+ d) If the work has interactive user interfaces, each must display
	231	+ Appropriate Legal Notices; however, if the Program has interactive
	232	+ interfaces that do not display Appropriate Legal Notices, your
	233	+ work need not make them do so.
	234	+
	235	+ A compilation of a covered work with other separate and independent
	236	+works, which are not by their nature extensions of the covered work,
	237	+and which are not combined with it such as to form a larger program,
	238	+in or on a volume of a storage or distribution medium, is called an
	239	+"aggregate" if the compilation and its resulting copyright are not
	240	+used to limit the access or legal rights of the compilation's users
	241	+beyond what the individual works permit. Inclusion of a covered work
	242	+in an aggregate does not cause this License to apply to the other
	243	+parts of the aggregate.
	244	+
	245	+ 6. Conveying Non-Source Forms.
	246	+
	247	+ You may convey a covered work in object code form under the terms
	248	+of sections 4 and 5, provided that you also convey the
	249	+machine-readable Corresponding Source under the terms of this License,
	250	+in one of these ways:
	251	+
	252	+ a) Convey the object code in, or embodied in, a physical product
	253	+ (including a physical distribution medium), accompanied by the
	254	+ Corresponding Source fixed on a durable physical medium
	255	+ customarily used for software interchange.
	256	+
	257	+ b) Convey the object code in, or embodied in, a physical product
	258	+ (including a physical distribution medium), accompanied by a
	259	+ written offer, valid for at least three years and valid for as
	260	+ long as you offer spare parts or customer support for that product
	261	+ model, to give anyone who possesses the object code either (1) a
	262	+ copy of the Corresponding Source for all the software in the
	263	+ product that is covered by this License, on a durable physical
	264	+ medium customarily used for software interchange, for a price no
	265	+ more than your reasonable cost of physically performing this
	266	+ conveying of source, or (2) access to copy the
	267	+ Corresponding Source from a network server at no charge.
	268	+
	269	+ c) Convey individual copies of the object code with a copy of the
	270	+ written offer to provide the Corresponding Source. This
	271	+ alternative is allowed only occasionally and noncommercially, and
	272	+ only if you received the object code with such an offer, in accord
	273	+ with subsection 6b.
	274	+
	275	+ d) Convey the object code by offering access from a designated
	276	+ place (gratis or for a charge), and offer equivalent access to the
	277	+ Corresponding Source in the same way through the same place at no
	278	+ further charge. You need not require recipients to copy the
	279	+ Corresponding Source along with the object code. If the place to
	280	+ copy the object code is a network server, the Corresponding Source
	281	+ may be on a different server (operated by you or a third party)
	282	+ that supports equivalent copying facilities, provided you maintain
	283	+ clear directions next to the object code saying where to find the
	284	+ Corresponding Source. Regardless of what server hosts the
	285	+ Corresponding Source, you remain obligated to ensure that it is
	286	+ available for as long as needed to satisfy these requirements.
	287	+
	288	+ e) Convey the object code using peer-to-peer transmission, provided
	289	+ you inform other peers where the object code and Corresponding
	290	+ Source of the work are being offered to the general public at no
	291	+ charge under subsection 6d.
	292	+
	293	+ A separable portion of the object code, whose source code is excluded
	294	+from the Corresponding Source as a System Library, need not be
	295	+included in conveying the object code work.
	296	+
	297	+ A "User Product" is either (1) a "consumer product", which means any
	298	+tangible personal property which is normally used for personal, family,
	299	+or household purposes, or (2) anything designed or sold for incorporation
	300	+into a dwelling. In determining whether a product is a consumer product,
	301	+doubtful cases shall be resolved in favor of coverage. For a particular
	302	+product received by a particular user, "normally used" refers to a
	303	+typical or common use of that class of product, regardless of the status
	304	+of the particular user or of the way in which the particular user
	305	+actually uses, or expects or is expected to use, the product. A product
	306	+is a consumer product regardless of whether the product has substantial
	307	+commercial, industrial or non-consumer uses, unless such uses represent
	308	+the only significant mode of use of the product.
	309	+
	310	+ "Installation Information" for a User Product means any methods,
	311	+procedures, authorization keys, or other information required to install
	312	+and execute modified versions of a covered work in that User Product from
	313	+a modified version of its Corresponding Source. The information must
	314	+suffice to ensure that the continued functioning of the modified object
	315	+code is in no case prevented or interfered with solely because
	316	+modification has been made.
	317	+
	318	+ If you convey an object code work under this section in, or with, or
	319	+specifically for use in, a User Product, and the conveying occurs as
	320	+part of a transaction in which the right of possession and use of the
	321	+User Product is transferred to the recipient in perpetuity or for a
	322	+fixed term (regardless of how the transaction is characterized), the
	323	+Corresponding Source conveyed under this section must be accompanied
	324	+by the Installation Information. But this requirement does not apply
	325	+if neither you nor any third party retains the ability to install
	326	+modified object code on the User Product (for example, the work has
	327	+been installed in ROM).
	328	+
	329	+ The requirement to provide Installation Information does not include a
	330	+requirement to continue to provide support service, warranty, or updates
	331	+for a work that has been modified or installed by the recipient, or for
	332	+the User Product in which it has been modified or installed. Access to a
	333	+network may be denied when the modification itself materially and
	334	+adversely affects the operation of the network or violates the rules and
	335	+protocols for communication across the network.
	336	+
	337	+ Corresponding Source conveyed, and Installation Information provided,
	338	+in accord with this section must be in a format that is publicly
	339	+documented (and with an implementation available to the public in
	340	+source code form), and must require no special password or key for
	341	+unpacking, reading or copying.
	342	+
	343	+ 7. Additional Terms.
	344	+
	345	+ "Additional permissions" are terms that supplement the terms of this
	346	+License by making exceptions from one or more of its conditions.
	347	+Additional permissions that are applicable to the entire Program shall
	348	+be treated as though they were included in this License, to the extent
	349	+that they are valid under applicable law. If additional permissions
	350	+apply only to part of the Program, that part may be used separately
	351	+under those permissions, but the entire Program remains governed by
	352	+this License without regard to the additional permissions.
	353	+
	354	+ When you convey a copy of a covered work, you may at your option
	355	+remove any additional permissions from that copy, or from any part of
	356	+it. (Additional permissions may be written to require their own
	357	+removal in certain cases when you modify the work.) You may place
	358	+additional permissions on material, added by you to a covered work,
	359	+for which you have or can give appropriate copyright permission.
	360	+
	361	+ Notwithstanding any other provision of this License, for material you
	362	+add to a covered work, you may (if authorized by the copyright holders of
	363	+that material) supplement the terms of this License with terms:
	364	+
	365	+ a) Disclaiming warranty or limiting liability differently from the
	366	+ terms of sections 15 and 16 of this License; or
	367	+
	368	+ b) Requiring preservation of specified reasonable legal notices or
	369	+ author attributions in that material or in the Appropriate Legal
	370	+ Notices displayed by works containing it; or
	371	+
	372	+ c) Prohibiting misrepresentation of the origin of that material, or
	373	+ requiring that modified versions of such material be marked in
	374	+ reasonable ways as different from the original version; or
	375	+
	376	+ d) Limiting the use for publicity purposes of names of licensors or
	377	+ authors of the material; or
	378	+
	379	+ e) Declining to grant rights under trademark law for use of some
	380	+ trade names, trademarks, or service marks; or
	381	+
	382	+ f) Requiring indemnification of licensors and authors of that
	383	+ material by anyone who conveys the material (or modified versions of
	384	+ it) with contractual assumptions of liability to the recipient, for
	385	+ any liability that these contractual assumptions directly impose on
	386	+ those licensors and authors.
	387	+
	388	+ All other non-permissive additional terms are considered "further
	389	+restrictions" within the meaning of section 10. If the Program as you
	390	+received it, or any part of it, contains a notice stating that it is
	391	+governed by this License along with a term that is a further
	392	+restriction, you may remove that term. If a license document contains
	393	+a further restriction but permits relicensing or conveying under this
	394	+License, you may add to a covered work material governed by the terms
	395	+of that license document, provided that the further restriction does
	396	+not survive such relicensing or conveying.
	397	+
	398	+ If you add terms to a covered work in accord with this section, you
	399	+must place, in the relevant source files, a statement of the
	400	+additional terms that apply to those files, or a notice indicating
	401	+where to find the applicable terms.
	402	+
	403	+ Additional terms, permissive or non-permissive, may be stated in the
	404	+form of a separately written license, or stated as exceptions;
	405	+the above requirements apply either way.
	406	+
	407	+ 8. Termination.
	408	+
	409	+ You may not propagate or modify a covered work except as expressly
	410	+provided under this License. Any attempt otherwise to propagate or
	411	+modify it is void, and will automatically terminate your rights under
	412	+this License (including any patent licenses granted under the third
	413	+paragraph of section 11).
	414	+
	415	+ However, if you cease all violation of this License, then your
	416	+license from a particular copyright holder is reinstated (a)
	417	+provisionally, unless and until the copyright holder explicitly and
	418	+finally terminates your license, and (b) permanently, if the copyright
	419	+holder fails to notify you of the violation by some reasonable means
	420	+prior to 60 days after the cessation.
	421	+
	422	+ Moreover, your license from a particular copyright holder is
	423	+reinstated permanently if the copyright holder notifies you of the
	424	+violation by some reasonable means, this is the first time you have
	425	+received notice of violation of this License (for any work) from that
	426	+copyright holder, and you cure the violation prior to 30 days after
	427	+your receipt of the notice.
	428	+
	429	+ Termination of your rights under this section does not terminate the
	430	+licenses of parties who have received copies or rights from you under
	431	+this License. If your rights have been terminated and not permanently
	432	+reinstated, you do not qualify to receive new licenses for the same
	433	+material under section 10.
	434	+
	435	+ 9. Acceptance Not Required for Having Copies.
	436	+
	437	+ You are not required to accept this License in order to receive or
	438	+run a copy of the Program. Ancillary propagation of a covered work
	439	+occurring solely as a consequence of using peer-to-peer transmission
	440	+to receive a copy likewise does not require acceptance. However,
	441	+nothing other than this License grants you permission to propagate or
	442	+modify any covered work. These actions infringe copyright if you do
	443	+not accept this License. Therefore, by modifying or propagating a
	444	+covered work, you indicate your acceptance of this License to do so.
	445	+
	446	+ 10. Automatic Licensing of Downstream Recipients.
	447	+
	448	+ Each time you convey a covered work, the recipient automatically
	449	+receives a license from the original licensors, to run, modify and
	450	+propagate that work, subject to this License. You are not responsible
	451	+for enforcing compliance by third parties with this License.
	452	+
	453	+ An "entity transaction" is a transaction transferring control of an
	454	+organization, or substantially all assets of one, or subdividing an
	455	+organization, or merging organizations. If propagation of a covered
	456	+work results from an entity transaction, each party to that
	457	+transaction who receives a copy of the work also receives whatever
	458	+licenses to the work the party's predecessor in interest had or could
	459	+give under the previous paragraph, plus a right to possession of the
	460	+Corresponding Source of the work from the predecessor in interest, if
	461	+the predecessor has it or can get it with reasonable efforts.
	462	+
	463	+ You may not impose any further restrictions on the exercise of the
	464	+rights granted or affirmed under this License. For example, you may
	465	+not impose a license fee, royalty, or other charge for exercise of
	466	+rights granted under this License, and you may not initiate litigation
	467	+(including a cross-claim or counterclaim in a lawsuit) alleging that
	468	+any patent claim is infringed by making, using, selling, offering for
	469	+sale, or importing the Program or any portion of it.
	470	+
	471	+ 11. Patents.
	472	+
	473	+ A "contributor" is a copyright holder who authorizes use under this
	474	+License of the Program or a work on which the Program is based. The
	475	+work thus licensed is called the contributor's "contributor version".
	476	+
	477	+ A contributor's "essential patent claims" are all patent claims
	478	+owned or controlled by the contributor, whether already acquired or
	479	+hereafter acquired, that would be infringed by some manner, permitted
	480	+by this License, of making, using, or selling its contributor version,
	481	+but do not include claims that would be infringed only as a
	482	+consequence of further modification of the contributor version. For
	483	+purposes of this definition, "control" includes the right to grant
	484	+patent sublicenses in a manner consistent with the requirements of
	485	+this License.
	486	+
	487	+ Each contributor grants you a non-exclusive, worldwide, royalty-free
	488	+patent license under the contributor's essential patent claims, to
	489	+make, use, sell, offer for sale, import and otherwise run, modify and
	490	+propagate the contents of its contributor version.
	491	+
	492	+ In the following three paragraphs, a "patent license" is any express
	493	+agreement or commitment, however denominated, not to enforce a patent
	494	+(such as an express permission to practice a patent or covenant not to
	495	+sue for patent infringement). To "grant" such a patent license to a
	496	+party means to make such an agreement or commitment not to enforce a
	497	+patent against the party.
	498	+
	499	+ If you convey a covered work, knowingly relying on a patent license,
	500	+and the Corresponding Source of the work is not available for anyone
	501	+to copy, free of charge and under the terms of this License, through a
	502	+publicly available network server or other readily accessible means,
	503	+then you must either (1) cause the Corresponding Source to be so
	504	+available, or (2) arrange to deprive yourself of the benefit of the
	505	+patent license for this particular work, or (3) arrange, in a manner
	506	+consistent with the requirements of this License, to extend the patent
	507	+license to downstream recipients. "Knowingly relying" means you have
	508	+actual knowledge that, but for the patent license, your conveying the
	509	+covered work in a country, or your recipient's use of the covered work
	510	+in a country, would infringe one or more identifiable patents in that
	511	+country that you have reason to believe are valid.
	512	+
	513	+ If, pursuant to or in connection with a single transaction or
	514	+arrangement, you convey, or propagate by procuring conveyance of, a
	515	+covered work, and grant a patent license to some of the parties
	516	+receiving the covered work authorizing them to use, propagate, modify
	517	+or convey a specific copy of the covered work, then the patent license
	518	+you grant is automatically extended to all recipients of the covered
	519	+work and works based on it.
	520	+
	521	+ A patent license is "discriminatory" if it does not include within
	522	+the scope of its coverage, prohibits the exercise of, or is
	523	+conditioned on the non-exercise of one or more of the rights that are
	524	+specifically granted under this License. You may not convey a covered
	525	+work if you are a party to an arrangement with a third party that is
	526	+in the business of distributing software, under which you make payment
	527	+to the third party based on the extent of your activity of conveying
	528	+the work, and under which the third party grants, to any of the
	529	+parties who would receive the covered work from you, a discriminatory
	530	+patent license (a) in connection with copies of the covered work
	531	+conveyed by you (or copies made from those copies), or (b) primarily
	532	+for and in connection with specific products or compilations that
	533	+contain the covered work, unless you entered into that arrangement,
	534	+or that patent license was granted, prior to 28 March 2007.
	535	+
	536	+ Nothing in this License shall be construed as excluding or limiting
	537	+any implied license or other defenses to infringement that may
	538	+otherwise be available to you under applicable patent law.
	539	+
	540	+ 12. No Surrender of Others' Freedom.
	541	+
	542	+ If conditions are imposed on you (whether by court order, agreement or
	543	+otherwise) that contradict the conditions of this License, they do not
	544	+excuse you from the conditions of this License. If you cannot convey a
	545	+covered work so as to satisfy simultaneously your obligations under this
	546	+License and any other pertinent obligations, then as a consequence you may
	547	+not convey it at all. For example, if you agree to terms that obligate you
	548	+to collect a royalty for further conveying from those to whom you convey
	549	+the Program, the only way you could satisfy both those terms and this
	550	+License would be to refrain entirely from conveying the Program.
	551	+
	552	+ 13. Use with the GNU Affero General Public License.
	553	+
	554	+ Notwithstanding any other provision of this License, you have
	555	+permission to link or combine any covered work with a work licensed
	556	+under version 3 of the GNU Affero General Public License into a single
	557	+combined work, and to convey the resulting work. The terms of this
	558	+License will continue to apply to the part which is the covered work,
	559	+but the special requirements of the GNU Affero General Public License,
	560	+section 13, concerning interaction through a network will apply to the
	561	+combination as such.
	562	+
	563	+ 14. Revised Versions of this License.
	564	+
	565	+ The Free Software Foundation may publish revised and/or new versions of
	566	+the GNU General Public License from time to time. Such new versions will
	567	+be similar in spirit to the present version, but may differ in detail to
	568	+address new problems or concerns.
	569	+
	570	+ Each version is given a distinguishing version number. If the
	571	+Program specifies that a certain numbered version of the GNU General
	572	+Public License "or any later version" applies to it, you have the
	573	+option of following the terms and conditions either of that numbered
	574	+version or of any later version published by the Free Software
	575	+Foundation. If the Program does not specify a version number of the
	576	+GNU General Public License, you may choose any version ever published
	577	+by the Free Software Foundation.
	578	+
	579	+ If the Program specifies that a proxy can decide which future
	580	+versions of the GNU General Public License can be used, that proxy's
	581	+public statement of acceptance of a version permanently authorizes you
	582	+to choose that version for the Program.
	583	+
	584	+ Later license versions may give you additional or different
	585	+permissions. However, no additional obligations are imposed on any
	586	+author or copyright holder as a result of your choosing to follow a
	587	+later version.
	588	+
	589	+ 15. Disclaimer of Warranty.
	590	+
	591	+ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
	592	+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
	593	+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
	594	+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
	595	+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
	596	+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
	597	+IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
	598	+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
	599	+
	600	+ 16. Limitation of Liability.
	601	+
	602	+ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
	603	+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
	604	+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
	605	+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
	606	+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
	607	+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
	608	+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
	609	+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
	610	+SUCH DAMAGES.
	611	+
	612	+ 17. Interpretation of Sections 15 and 16.
	613	+
	614	+ If the disclaimer of warranty and limitation of liability provided
	615	+above cannot be given local legal effect according to their terms,
	616	+reviewing courts shall apply local law that most closely approximates
	617	+an absolute waiver of all civil liability in connection with the
	618	+Program, unless a warranty or assumption of liability accompanies a
	619	+copy of the Program in return for a fee.
	620	+
	621	+ END OF TERMS AND CONDITIONS
	622	+
	623	+ How to Apply These Terms to Your New Programs
	624	+
	625	+ If you develop a new program, and you want it to be of the greatest
	626	+possible use to the public, the best way to achieve this is to make it
	627	+free software which everyone can redistribute and change under these terms.
	628	+
	629	+ To do so, attach the following notices to the program. It is safest
	630	+to attach them to the start of each source file to most effectively
	631	+state the exclusion of warranty; and each file should have at least
	632	+the "copyright" line and a pointer to where the full notice is found.
	633	+
	634	+ <one line to give the program's name and a brief idea of what it does.>
	635	+ Copyright (C) <year> <name of author>
	636	+
	637	+ This program is free software: you can redistribute it and/or modify
	638	+ it under the terms of the GNU General Public License as published by
	639	+ the Free Software Foundation, either version 3 of the License, or
	640	+ (at your option) any later version.
	641	+
	642	+ This program is distributed in the hope that it will be useful,
	643	+ but WITHOUT ANY WARRANTY; without even the implied warranty of
	644	+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	645	+ GNU General Public License for more details.
	646	+
	647	+ You should have received a copy of the GNU General Public License
	648	+ along with this program. If not, see <http://www.gnu.org/licenses/>.
	649	+
	650	+Also add information on how to contact you by electronic and paper mail.
	651	+
	652	+ If the program does terminal interaction, make it output a short
	653	+notice like this when it starts in an interactive mode:
	654	+
	655	+ <program> Copyright (C) <year> <name of author>
	656	+ This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
	657	+ This is free software, and you are welcome to redistribute it
	658	+ under certain conditions; type `show c' for details.
	659	+
	660	+The hypothetical commands `show w' and `show c' should show the appropriate
	661	+parts of the General Public License. Of course, your program's commands
	662	+might be different; for a GUI interface, you would use an "about box".
	663	+
	664	+ You should also get your employer (if you work as a programmer) or school,
	665	+if any, to sign a "copyright disclaimer" for the program, if necessary.
	666	+For more information on this, and how to apply and follow the GNU GPL, see
	667	+<http://www.gnu.org/licenses/>.
	668	+
	669	+ The GNU General Public License does not permit incorporating your program
	670	+into proprietary programs. If your program is a subroutine library, you
	671	+may consider it more useful to permit linking proprietary applications with
	672	+the library. If this is what you want to do, use the GNU Lesser General
	673	+Public License instead of this License. But first, please read
	674	+<http://www.gnu.org/philosophy/why-not-lgpl.html>.
...	...

README.md 0 → 100644

View file @47b5f8d

	1	+++ a/README.md
	1	+CLI Library
	2	+===========
	3	+
	4	+Library to build a real-time serial (or network) command-line interface (CLI) to
	5	+configure or control your Arduino or compatible microcontroller.
	6	+
	7	+This is Version 1.0, the latest version, documentation and bugtracker are
	8	+available on my [GitLab instance](https://gitlab.lindenaar.net/arduino/CLI)
	9	+
	10	+Copyright (c) 2019 Frederik Lindenaar. free for distribution under the
	11	+GNU License, see [below](#license)
	12	+
	13	+
	14	+Introduction
	15	+------------
	16	+Frequently need to interact with a microcontroller to, for example:
	17	+ * see what's stored in the embedded or an I2C EEPROM
	18	+ * check that all I2C devices are detected and responding
	19	+ * check or set a connected real-time clock
	20	+ * check or set configuration options (I don't hard-code config)
	21	+
	22	+Since I don't like reprogramming the microcontroller every time this is needed,
	23	+I wrote this library to provide a Command Line Interface over a Serial / USB
	24	+line. The library includes a number of commands that can be included where
	25	+applicable (which I expect will grow over time as I build more) so that it can
	26	+be used as a toolbox to start your development without having to worry about
	27	+stuff that could be standard. At this moment it includes the following commands:
	28	+ * `eeprom_dump` to display the contents of the built-in EEPROM
	29	+ * `i2c_scan` to scan the I2C bus for slave devices
	30	+ * `i2c_dump` to display the contents of I2C attached EEPROM or Memory
	31	+ * `reset` to restart the microcontroller (software reset)
	32	+ * `help` to display available commands and provided help on how to use them
	33	+
	34	+See below how to use the Library, to get an idea on how to use the library,
	35	+have a look at the examples included:
	36	+ * _Blink_: control the Blink example (using the built-in LED) using a
	37	+ Serial/USB console to change its blink rate or turn it on or off
	38	+ * _Debug_: CLI with the built-in debug commands listed above
	39	+ * _DS1307RTC_: CLI to read/set an DS1307 Real-Time Clock module (includes
	40	+ the built-in commands to access a module's NVRAM and EEPROM)
	41	+
	42	+
	43	+Download / Installation
	44	+-----------------------
	45	+At this moment this library is not yet available directly from the Arduino IDE
	46	+but has to be installed manually. For this, download the latest distribution
	47	+.zip file and install it using the following links:
	48	+ * From my GitLab instance, download to your computer the
	49	+ [Latest .zip archive](https://gitlab.lindenaar.net/arduino/CLI/repository/archive.zip)
	50	+ * Follow the documentation for the Arduino IDE on
	51	+ [importing a .zip Library](https://www.arduino.cc/en/Guide/Libraries#toc4).
	52	+ Alternatively, you can also extract the downloaded .zip and follow the steps
	53	+ for [manual Installation](https://www.arduino.cc/en/Guide/Libraries#toc5)
	54	+
	55	+You can also use `git` to checkout the latest version from my repository with
	56	+
	57	+```
	58	+ git clone https://gitlab.lindenaar.net/arduino/CLI.git
	59	+```
	60	+
	61	+so that it is easy to upgrade in the future. To find where to checkout check the
	62	+guide for [manual Installation](https://www.arduino.cc/en/Guide/Libraries#toc5).
	63	+
	64	+
	65	+Using the library
	66	+-----------------
	67	+Before adding this library to your code, it is important to realize that by
	68	+adding the CLI you are builing a so-called real-time system. The microcontroller
	69	+should be able to perform it's main task (normally not responding to Serial/USB
	70	+input) and in the background listen to commands given through the CLI. As most
	71	+microcontrollers have only a single CPU and no OS that can multitask, all logic
	72	+is handled from the main `loop()` function. As a consequence, one should avoid
	73	+writing code that waits (e.g. using the `delay()` function) but instead create
	74	+a loop that does not wait/block but determines whether to do something and if
	75	+not moves on to the next task.
	76	+
	77	+### Writing a real-time (i.e. non-blocking) loop
	78	+Looking at the Arduino IDE's standard Blink example (probably the starting point
	79	+for most when starting with the platform), you see the following code in `loop`:
	80	+
	81	+~~~
	82	+// the loop function runs over and over again forever
	83	+void loop() {
	84	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on (HIGH is the voltage level)
	85	+ delay(1000); // wait for a second
	86	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off by making the voltage LOW
	87	+ delay(1000); // wait for a second
	88	+}
	89	+~~~
	90	+
	91	+While this is perfectly fine code when the microcontroller has nothing else to
	92	+do, for a background CLI this would cause 1 second delays between each check for
	93	+input (ignoring more complex interrupt-driven approaches, which have their own
	94	+challenges). The key for making this loop non-blocking is to change it so that
	95	+it no longer waits but each time checks if it needs to change the LED status
	96	+instead, like in the example below:
	97	+
	98	+~~~
	99	+// variable to be preserved
	100	+unsigned long last_blink = 0;
	101	+
	102	+// the loop function runs over and over again forever
	103	+void loop() {
	104	+ // millis() will wrap every 49 days, below code is wrap-proof
	105	+ if (millis() - last_blink > 1000) { // last_blink was longer ago than delay?
	106	+ last_blink = millis(); // led state will change, store when
	107	+ if(digitalRead(LED_BUILTIN)) { // check if the LED is on or off
	108	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off by making the pin LOW
	109	+ } else {
	110	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on by making the pin HIGH
	111	+ }
	112	+ }
	113	+}
	114	+~~~
	115	+
	116	+This code uses the Arduino platform function `millis()` to obtain how long the
	117	+code is running (in milliseconds) and keeps track of when the LED state changed
	118	+last in variable `last_blink` (stored outside the loop so it is preserved).
	119	+The loop now simply checks every time whether the last blink was more than 1000
	120	+milliseconds ago and if so changes the LED state, otherwise it does nothing.
	121	+Please note that the above code was kept as much in line with the original Blink
	122	+example though could also be written as:
	123	+
	124	+~~~
	125	+// variable to be preserved
	126	+unsigned long last_blink = 0;
	127	+
	128	+// the loop function runs over and over again forever
	129	+void loop() {
	130	+ // millis() will wrap every 49 days, below code is wrap-proof
	131	+ if (millis() - last_blink > 1000) { // last_blink was longer ago than delay?
	132	+ last_blink = millis(); // led state will change, store when
	133	+ digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // invert LED PIN
	134	+ }
	135	+}
	136	+~~~
	137	+
	138	+Once the loop of your code is non-blocking, the CLI can be added to your Sketch.
	139	+
	140	+### Adding the CLI to a Sketch
	141	+Adding the CLI to your sketch is pretty straightforward, first include `CLI.h`
	142	+at the top of your sketch like this:
	143	+
	144	+~~~
	145	+#include <CLI.h>
	146	+~~~
	147	+
	148	+Next instantiate the CLI object by adding the following above (and outside) your
	149	+`setup()` and `loop()` functions:
	150	+
	151	+~~~
	152	+// Initialize the Command Line Interface
	153	+CLI CLI(Serial); // Initialize the CLI, telling it to attach to Serial
	154	+~~~
	155	+
	156	+Directly under the instantation of the `CLI` object commands can be instantiated
	157	+(added) like is shown below for the built-in Help command:
	158	+
	159	+~~~
	160	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
	161	+~~~
	162	+
	163	+The constructor of each command requires a `CLI` to register with to make the
	164	+implemented command available in the CLI.
	165	+Next in your `loop()`, place the following logic at the top:
	166	+
	167	+~~~
	168	+// handle CLI, if this returns true a command is running so skip code block
	169	+if (!CLI.process()) {
	170	+ // Code to run when no command is executing, make sure it is non-blocking...
	171	+}
	172	+// Code to execute every loop goes here, make sure it is non-blocking...
	173	+~~~
	174	+
	175	+The `CLI.process()` method handles the Command Line Interpreter; it responds to
	176	+user input, parses the command and executes the command code. To ensure that
	177	+this is also non-blocking, each of these steps is executed in smaller chunks so
	178	+that your main logic can be intertwined with the execution of the CLI logic. The
	179	+`CLI.process()` method will return `true` if a command is still executing so by
	180	+placing logic inside the `if() { ... }` block, you ensure it only runs when the
	181	+CLI is not doing anything while if you put it outside the block it will always
	182	+be executed. This can also be used to add an LED indicator to display whether
	183	+the CLI is executing as is shown in the below full sketch example (which shows
	184	+how a basic full implementation would look like):
	185	+
	186	+~~~
	187	+#include <CLI.h>
	188	+
	189	+// Initialize the Command Line Interface
	190	+CLI CLI(Serial); // Initialize the CLI, telling it to attach to Serial
	191	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
	192	+
	193	+
	194	+// the setup function runs once when you reset or power the board
	195	+void setup() {
	196	+ // Initialize digital pin LED_BUILTIN as an output.
	197	+ pinMode(LED_BUILTIN, OUTPUT);
	198	+
	199	+ // Initialize the Serial port for the CLI
	200	+ while (!Serial); // For Leonardo: wait for serial USB to connect
	201	+ Serial.begin(9600);
	202	+}
	203	+
	204	+
	205	+// the loop function runs over and over again forever
	206	+void loop() {
	207	+ // handle CLI, if this returns true a command is running so skip code block
	208	+ if (CLI.process()) {
	209	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on when processing CLI command
	210	+ } else {
	211	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off when CLI command not active
	212	+ // Code to run when no command is executing, make sure it is non-blocking...
	213	+ }
	214	+ // Code to execute every loop goes here, make sure it is non-blocking...
	215	+}
	216	+~~~
	217	+
	218	+You can run the above code by creating a new sketch and replacing its contents
	219	+with the full example above. Please also have a look at the examples provided as
	220	+they give a better view on what can be done and how to include a CLI in your
	221	+sketch.
	222	+
	223	+#### CLI on the Serial port
	224	+As you can see in the above example, the CLI object is initiated and on `Serial`
	225	+and used to instantiate the `Help_Command` while `Serial.begin()` is only called
	226	+from setup() (i.e. afterwards). Due to the way the initialization of the Arduino
	227	+platform works, it is not possible to use `Serial.begin()` before `setup()` is
	228	+called as things like interrupts and other boot-strap initialization (including
	229	+that of the Serial port) has not taken place yet. For this reason the CLI object
	230	+cannot initialize a `Serial` port but you have to do this from your `setup()`
	231	+routine (which doesn't really matter and also gives you full control over it)
	232	+but should not be forgotten (as the CLI won't work then).
	233	+Please note that due to this it is also not possible to use `Serial.print()` in
	234	+a constructor (this has nothing do to with this library but is a quirk of the
	235	+Arduino platform).
	236	+
	237	+#### CLI object parameters
	238	+The CLI object supports printing a banner upon startup and allows to configure
	239	+the defaults prompt ( `> `). To reduce the memory usage, the passed string for
	240	+either must be stored in `PROGMEM` (program memory, i.e. with the program in
	241	+Flash). Both parameters can be passed to the constructor when initializing the
	242	+`CLI` object like this:
	243	+
	244	+~~~
	245	+const char CLI_banner[] PROGMEM = "My Microcontroller v1.0 CLI";
	246	+const char CLI_prompt[] PROGMEM = "mm> ";
	247	+CLI CLI(Serial, CLI_banner, CLI_prompt);
	248	+~~~
	249	+
	250	+Currently both must hence be hardcoded static strings and there is no way to
	251	+make them dynamic or change them. This is a conscious design choice to reduce
	252	+the size of the code and the memory it requires. In case you have a good use
	253	+case to reconsider this decision, let's discuss and for that please do
	254	+(raise an issue here)[https://gitlab.lindenaar.net/arduino/CLI/issues].
	255	+
	256	+#### CLI is a `Stream`
	257	+The CLI Object implements a Stream so it can be used as well to interact with
	258	+the user, both from a command as well as from your main loop. Besides the CLI
	259	+implementation described in this document and the `print()` family of functions,
	260	+it also provides:
	261	+ * `print_P (const char *str PROGMEM)` to print a string stored in `PROGMEM`
	262	+ * `print2digits(uint8_t num, char filler = '0', uint8_t base=10)`
	263	+ to print a number with at least 2 digits (useful for `HEX` bytes)
	264	+ * `print_mem(uint16_t addr, const uint8_t buff[], uint8_t len, uint8_t width=16)`
	265	+ to dump a memory block in HEX and ASCII (`addr` is the startaddress to print)
	266	+
	267	+
	268	+### Implementing a Command
	269	+CLI commands are implemented as separate classes that register themselves with
	270	+the CLI upon instantiation. The actions to implement for a command are:
	271	+ 1. instantiate - the command's class is instantiated and registers with a CLI
	272	+ 2. set parameters - the command parses the user's parameters for the execution
	273	+ 3. execute - the command performs it's tasks using the parameters provided.
	274	+
	275	+To implement a new CLI command, one should inherit from `CLI_Command`
	276	+
	277	+~~~
	278	+class CLI_Command {
	279	+ public:
	280	+ CLI_Command(CLI &cli, const char *command PROGMEM,
	281	+ const char *description PROGMEM,
	282	+ const char *help PROGMEM = NULL);
	283	+ virtual bool setparams(const char *params);
	284	+ virtual bool execute(CLI &cli) = 0;
	285	+};
	286	+~~~
	287	+
	288	+and implement it's public methods. At least a constructor (calling the one from
	289	+`CLI_Command`) and the `execute()` method must be implemented. The class has a
	290	+default implementation for the `setparams()` method that accepts no parameters
	291	+that can be used for commands that do need parameters. The details of the
	292	+implementation steps are covered in the next sections to demonstrate how to
	293	+implement a "hello" command accepting a parameter and printing that.
	294	+
	295	+#### Implementation (Class Definition)
	296	+The first step for the implementation of our "hello" command is to define a
	297	+class `Hello_Command` inheriting from `CLI_Command`. In this case we implement
	298	+all three methods as we want to accept parameter(s) and need the private
	299	+variable `_params` to store it in `setparams()` to be used by `execute()`. The
	300	+definition of this basic class looks like:
	301	+
	302	+~~~
	303	+class Hello_Command : CLI_Command {
	304	+ const char *_params;
	305	+ public:
	306	+ Hello_Command(CLI &cli);
	307	+ bool setparams(const char *params);
	308	+ bool execute(CLI &cli);
	309	+};
	310	+~~~
	311	+
	312	+Although it is possible to define the method in the definition, in this example
	313	+they will be defined separately first. See the full code at the end of this
	314	+section that implements the methods inline.
	315	+
	316	+#### Instantiate (Class constructor)
	317	+The implementation of the constructor can be very simple; call the constructor
	318	+of `CLI_Command` with the following parameters:
	319	+ 1. instance of `CLI` class to register with (should be passed as parameter)
	320	+ 2. (static) string in `PROGMEM` with the name of the command
	321	+ 3. (static) string in `PROGMEM` with a short (1-line) command description
	322	+ 4. (static) string in `PROGMEM` with additional usage information
	323	+
	324	+below the implementation of the example "hello" command with empty constructor
	325	+(as no functional initiation is required) only calling the parent `CLI_Command`
	326	+with the above parameters:
	327	+
	328	+~~~
	329	+Hello_Command::Hello_Command(CLI &cli) : CLI_Command(&cli,
	330	+ PSTR("hello"),
	331	+ PSTR("Print an \"Hello\" greeting message"),
	332	+ PSTR("Usage:\thello <name>\n"
	333	+ "Where:\t<name>\ta string to include in the greeting")) { };
	334	+~~~
	335	+
	336	+The above uses the `PSTR()` macro to inline define the static strings for the
	337	+command name, description and help text. These normally are static and hence
	338	+hardcoded. The base implementation of the `Command` class takes care of storing
	339	+the references and making them available. It will also register the command with
	340	+the `CLI` instance provided. As already mentioned, the library assumes these are
	341	+in `PROGMEM` so please make sure your sketch stores them there.
	342	+
	343	+#### Set parameters (`setparams(const char *params)` method)
	344	+When the user invokes a command, the `setparams()` method is called with the
	345	+parameters the user provided after the command. This allows the command to
	346	+parse the parameters provided and do whatever is necessary for the command to
	347	+use this information (i.e. store it in an efficient way for `execute()`).
	348	+
	349	+The `setparams()` method is always called once when the user enters a command so
	350	+that it can ensure that everything is ready for the command's `execute()` method
	351	+to be invoked. It should return `true` in case the parameters are valid. In case
	352	+`setparams()` returns `false`, the execution of the command is aborted and its
	353	+`execute()` is never called but a standard error message is given instead.
	354	+
	355	+The `params` provided is a pointer to the start of the parameters with trailing
	356	+spaces removed and terminated with a `char(0)`. In case no (or only whitespace)
	357	+parameters were provided, this method is called with `NULL` so an Implementation
	358	+does not have to check for empty strings. As the CLI should not block the main
	359	+flow, make sure the parsing is efficient and keep it simple so that this method
	360	+(which is only called once for each command) does not take long.
	361	+
	362	+A very simple implementation for `setparams()` is provided below for our `hello`
	363	+command. This simply stores the pointer of the parameter string provided an will
	364	+result in a `true` result in case a parameter is provided or a `false` result
	365	+when the user did not provide any parameters.
	366	+
	367	+~~~
	368	+bool Hello_Command::setparams(const char *params) {
	369	+ _params = params;
	370	+ return (params);
	371	+}
	372	+~~~
	373	+
	374	+Often the parse will more complex as it is needs to parse the string provided.
	375	+The design choice to have this implemented in the command is that this provides
	376	+the greatest flexibility and does not assume anything w.r.t. how or which
	377	+parameters are passed. The library does include a number of support functions
	378	+that can be used to parse parameters and encode them in flags.
	379	+
	380	+Please note that any attribute / variable used to store parameters are global
	381	+(part of the object memory) so will eat up ram. Use them wisely so you don't
	382	+run out of RAM on the smaller Arduino platforms that have only 2Kb or RAM.
	383	+
	384	+#### Execute logic (`execute(CLI &cli)` method)
	385	+The `execute()` method contains the actual implementation of the command. It is
	386	+called with a reference to the `CLI` so that there is no need to store that in
	387	+the object. To support a real-time implementation even if the command needs a
	388	+longer time (or is waiting), the implementation can return `true` to pause the
	389	+current invocation of the `execute` method and will be called in the next main
	390	+`loop()` cycle again. This allows for returning to the main loop in between of
	391	+waiting or execution of the command so that the main loop can continue as well.
	392	+
	393	+Before `execute()` is the first time, `setparams()` is called once to process
	394	+parameters from the user and perform initialization or setup needed. As long
	395	+as `execute()` returns `true` it will continue to be invoked again until it
	396	+returns `false` to signal that the command's execution is complete. The Command
	397	+Line Interface will only process user input again when the command is completed
	398	+(so a command can also prompt the user for additional input)
	399	+
	400	+Below the implementation of the `hello` command, which is pretty simple as it
	401	+only prints "Hello" (stored in `PROGMEM` followed by the string the user
	402	+provided. It then returns `false` to signal to the `CLI` that it is done.
	403	+
	404	+~~~
	405	+bool Hello_Command::execute(CLI &cli) {
	406	+ cli.print_P(PSTR("Hello "));
	407	+ cli.println(_params);
	408	+ return false;
	409	+}
	410	+~~~
	411	+
	412	+Commands can be as complex as needed. For more extensive examples, please have a
	413	+look at the provided examples and built-in commands in `Commands.cpp`.
	414	+
	415	+#### Full Example Sketch for the Hello command
	416	+Below the full example sketch built up in the previous sections with the methods
	417	+implemented inline:
	418	+
	419	+~~~
	420	+#include <CLI.h>
	421	+
	422	+class Hello_Command : CLI_Command {
	423	+ const char *_params;
	424	+ public:
	425	+ Hello_Command(CLI &cli) :
	426	+ CLI_Command(cli,
	427	+ PSTR("hello"),
	428	+ PSTR("Print an \"Hello\" greeting message"),
	429	+ PSTR("Usage:\thello <name>\n"
	430	+ "Where:\t<name>\tstring to include in greeting")) { };
	431	+ bool setparams(const char *params) {
	432	+ _params = params;
	433	+ return (params);
	434	+ }
	435	+ bool execute(CLI &cli) {
	436	+ cli.print_P(PSTR("Hello "));
	437	+ cli.println(_params);
	438	+ return false;
	439	+ }
	440	+};
	441	+
	442	+// Initialize the Command Line Interface
	443	+const char CLI_banner[] PROGMEM = "Hello CLI v1.0";
	444	+CLI CLI(Serial, CLI_banner); // Initialize CLI, telling it to attach to Serial
	445	+Hello_Command Hello(CLI); // Initialize/Register above defined hello command
	446	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
	447	+
	448	+
	449	+// the setup function runs once when you reset or power the board
	450	+void setup() {
	451	+ // Initialize digital pin LED_BUILTIN as an output.
	452	+ pinMode(LED_BUILTIN, OUTPUT);
	453	+
	454	+ // Initialize the Serial port for the CLI
	455	+ while (!Serial); // For Leonardo: wait for serial USB to connect
	456	+ Serial.begin(9600);
	457	+}
	458	+
	459	+
	460	+// the loop function runs over and over again forever
	461	+void loop() {
	462	+ // handle CLI, if this returns true a command is running so skip code block
	463	+ if (CLI.process()) {
	464	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on when processing CLI command
	465	+ } else {
	466	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off when CLI command not active
	467	+ // Code to run when no command is executing, make sure it is non-blocking...
	468	+ }
	469	+ // Code to execute every loop goes here, make sure it is non-blocking...
	470	+}
	471	+~~~
	472	+
	473	+I hope this clarifies how this library can and should be used. In case you find
	474	+any issues with the documentation, code or examples, please do raise an issue
	475	+[here](https://gitlab.lindenaar.net/arduino/CLI/issues).
	476	+
	477	+
	478	+### Parser Support Functions
	479	+The library contains a number of support functions to ease with building a
	480	+parser for command parameters. These still need to be documented but can be found
	481	+already in `CLI_Utils.cpp` within the library and are used by the built-in
	482	+commands found in `Commands.cpp` and exampled included.
	483	+
	484	+
	485	+<a name="license">License</a>
	486	+=============================
	487	+This library, documentation and examples are free software: you can redistribute
	488	+them and/or modify them under the terms of the GNU General Public License as
	489	+published by the Free Software Foundation, either version 3 of the License, or
	490	+(at your option) any later version.
	491	+
	492	+This script, documentation and configuration examples are distributed in the
	493	+hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
	494	+warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	495	+General Public License for more details.
	496	+
	497	+You should have received a copy of the GNU General Public License along with
	498	+this program. If not, download it from <http://www.gnu.org/licenses/>.
	499	+
...	...

examples/Blink/Blink.ino 0 → 100644

View file @47b5f8d

	1	+++ a/examples/Blink/Blink.ino
	1	+/*
	2	+ Blink.ino - CLI library sample implementing a CLI for the Blink sample code
	3	+
	4	+ Version 1.0, latest version, documentation and bugtracker available at:
	5	+ https://gitlab.lindenaar.net/arduino/CLI
	6	+
	7	+ Copyright (c) 2019 Frederik Lindenaar
	8	+
	9	+ This example shows how to build a simple command line to control the default
	10	+ Blink example of the Arduino IDE. This requires additional code to control
	11	+ the parameters (maintained within the C++ objects for the commands) as well
	12	+ as a different main loop logic to become a real-time process with a Command
	13	+ Line in te backgrouns while blinking and no longer using delay() for timing.
	14	+
	15	+ The implementation provides the following commands available through the
	16	+ Serial Monitor (available from the Tools menu of the Arduino IDE):
	17	+ - mode display and/or set the LED mode (either on, off or blink)
	18	+ - delay display and/or set the blinking delay for the led
	19	+ - faster double the blinking rate (half the delay)
	20	+ - slower half the blinking rate (double the delay)
	21	+ - help show the available commands and how to use (builtin command)
	22	+
	23	+ For each of the commands an CLI_Command derived class is implemented with :
	24	+ - Private variables to hold the internal state of the command
	25	+ - Object constructor to set default values
	26	+ - a setparams() method to handle parameters (when applicable)
	27	+ - a execute() method for the implementation of the command
	28	+ - Getter (and Setter) methods to access object state (where applicable)
	29	+
	30	+ This sketch is free software: you can redistribute it and/or modify it under
	31	+ the terms of version 3 of the GNU General Public License as published by the
	32	+ Free Software Foundation, or (at your option) a later version of the license.
	33	+
	34	+ This code is distributed in the hope that it will be useful but WITHOUT ANY
	35	+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
	36	+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
	37	+
	38	+ You should have received a copy of the GNU General Public License along with
	39	+ this program. If not, visit <http://www.gnu.org/licenses/> to download it.
	40	+*/
	41	+
	42	+#include <CLI.h>
	43	+
	44	+enum LED_MODE { OFF, ON, BLINKING }; // LED modes implemented/supported
	45	+
	46	+#define BLINK_MIN_DELAY 25 // min blink delay is 25ms
	47	+#define BLINK_MAX_DELAY 10000 // max blink delay is 10s
	48	+
	49	+// Convert macro to string (https://gcc.gnu.org/onlinedocs/cpp/Stringizing.html)
	50	+#define TO_STRING(val) #val
	51	+#define VAL_TO_STRING(val) TO_STRING(val)
	52	+
	53	+
	54	+// Store mode command parameters as static PROGMEM strings (needed below)
	55	+const char CMD_MODE_PARAM_ON[] PROGMEM = "on";
	56	+const char CMD_MODE_PARAM_OFF[] PROGMEM = "off";
	57	+const char CMD_MODE_PARAM_BLINK[] PROGMEM = "blink";
	58	+
	59	+// struct stored in PROGMEM to map the parameters for mode command to a value
	60	+const struct CLI_Command_Param Mode_Command_Parameters[] PROGMEM = {
	61	+ { CMD_MODE_PARAM_ON, ON, },
	62	+ { CMD_MODE_PARAM_OFF, OFF, },
	63	+ { CMD_MODE_PARAM_BLINK, BLINKING, },
	64	+ { NULL }
	65	+};
	66	+
	67	+
	68	+class Mode_Command : CLI_Command { // Implementation of the mode command
	69	+ LED_MODE _mode; // Private variable to store current mode
	70	+ public:
	71	+ Mode_Command(CLI &cli, LED_MODE mode = OFF) : // Constructor with default initial mode
	72	+ CLI_Command(cli, // CLI to register with
	73	+ PSTR("mode"), // Command name
	74	+ PSTR("Set and/or show LED mode"), // Description
	75	+ PSTR("Usage:\tmode [<led_mode>]\n" // Usage Help
	76	+ "where <led_mode> is one of:\n"
	77	+ "\ton\tturn LED on\n"
	78	+ "\toff\tturn LED off\n"
	79	+ "\tblink\tblink the LED\n")), _mode(mode) { };
	80	+ bool setparams(const char *params) { // Called once before execute to process parameters
	81	+ if (params) { // Check if we have parameters
	82	+ // Use the CLI_STR_parseParam_P utility function to parse the parameter
	83	+ const struct CLI_Command_Param *p = CLI_STR_parseParam_P(params, Mode_Command_Parameters);
	84	+ if (!p) return false; // return false in case of an invalid parameter
	85	+ _mode = pgm_read_word(&p->uint16); // set led_mode to the one of the parameter
	86	+ if (_mode != BLINKING) // ensure LED state == led_mode if not blinking
	87	+ digitalWrite(LED_BUILTIN, _mode == ON);
	88	+ }
	89	+ return true; // Return true in case of no or a valid parameter
	90	+ }
	91	+ bool execute(CLI &cli) { // Implementation, called as long as it returns true
	92	+ cli.print_P(PSTR("LED mode is ")); // Simply show the LED mode (need to do that always)
	93	+ cli.print_P((_mode == ON) ? PSTR("ON") :
	94	+ (_mode == OFF) ? PSTR("OFF") :
	95	+ (_mode == BLINKING) ? PSTR("blink") : PSTR("unknown"));
	96	+ return false; // return false as we're done
	97	+ }
	98	+ inline LED_MODE get() { // Getter for the mode
	99	+ return _mode;
	100	+ }
	101	+ inline void set(LED_MODE mode) { // Setter for the mode
	102	+ _mode = mode;
	103	+ }
	104	+};
	105	+
	106	+
	107	+class Delay_Command : CLI_Command { // Implementation of the delay command
	108	+ unsigned int _delay; // Private variable to store current delay
	109	+ public:
	110	+ Delay_Command(CLI &cli) : // Constructor
	111	+ CLI_Command(cli, // CLI to register with
	112	+ PSTR("delay"), // Command name
	113	+ PSTR("set and/or show LED blink delay"), // Description
	114	+ PSTR("Usage:\tdelay [<blink_delay>]\n" // Usage Help
	115	+ "\twhere <blink_delay> is the delay in milliseconds (integer between "
	116	+ VAL_TO_STRING(BLINK_MIN_DELAY) " and " VAL_TO_STRING(BLINK_MAX_DELAY) ")\n")) {
	117	+ _delay = 1000;
	118	+ };
	119	+ bool setparams(const char *params) { // Called once before execute to process parameters
	120	+ if (params) { // Check if we have parameters
	121	+ int d;
	122	+ params = CLI_STR_parseInt(params, d); // parse params using CLI_STR_parseInt utility function
	123	+ if (params && !*params) { // check if an int was found and reached end of params
	124	+ return set(d); // return true if all OK or false when not within range
	125	+ }
	126	+ return false; // return false if no int or more param input was found
	127	+ }
	128	+ return true; // return true in case of no or a valid parameter
	129	+ }
	130	+ bool execute(CLI &cli) { // Implementation, called as long as it returns true
	131	+ cli.print_P(PSTR("blink delay ")); // Simply show the blink delay (need to do that always)
	132	+ cli.print(_delay);
	133	+ cli.print_P(PSTR(" milliseconds\n"));
	134	+ return false; // return false as we're done
	135	+ }
	136	+ inline unsigned int get() { // Getter for the mode
	137	+ return _delay;
	138	+ }
	139	+ inline bool set(unsigned int d) { // Setter for the mode, checking it is within range
	140	+ if (d < BLINK_MIN_DELAY \|\| d > BLINK_MAX_DELAY)
	141	+ return false; // Return false if new value is out of bounds
	142	+ _delay = d; // store new value
	143	+ return true; // return true as new value is OK
	144	+ }
	145	+};
	146	+
	147	+
	148	+class Faster_Command : CLI_Command { // Implementation of the faster command
	149	+ Delay_Command &_delay; // Private variable to store delay command
	150	+ public:
	151	+ Faster_Command(CLI &cli, Delay_Command &delay) : // Constructor, requires delay command reference
	152	+ CLI_Command(cli, // CLI to register with
	153	+ PSTR("faster"), // Command name
	154	+ PSTR("Blink faster")), // Description, no Usage Help provided
	155	+ _delay(delay) { }; // Store reference to delay command, empty constructor
	156	+ // Please note: no parameters will be accepted (using default setparams() implementation)
	157	+ bool execute(CLI &cli) { // Implementation, called as long as it returns true
	158	+ if (_delay.set(_delay.get() / 2)) { // Half the blink time, returns false if outside range
	159	+ _delay.setparams(0); // clear _delay's parameters as we call it's execute() next
	160	+ _delay.execute(cli); // call _delay's execute() method to print the delay
	161	+ } else {
	162	+ cli.print_P(PSTR("Can't blink faster"));// print an error message if half blink delay is out of bounds
	163	+ }
	164	+ return false; // return false as we're done
	165	+ }
	166	+};
	167	+
	168	+
	169	+class Slower_Command : CLI_Command { // Implementation of the slower command
	170	+ Delay_Command &_delay; // Private variable to store delay command
	171	+ public:
	172	+ Slower_Command(CLI &cli, Delay_Command &delay) : // Constructor, requires delay command reference
	173	+ CLI_Command(cli, // CLI to register with
	174	+ PSTR("slower"), // Command name
	175	+ PSTR("Blink slower")), // Description, no Usage Help provided
	176	+ _delay(delay) { }; // Store reference to delay command, empty constructor
	177	+ // Please note: no parameters will be accepted (using default setparams() implementation)
	178	+ bool execute(CLI &cli) { // Implementation, called as long as it returns true
	179	+ if (_delay.set(_delay.get() * 2)) { // Half the blink time, returns false if outside range
	180	+ _delay.setparams(0); // clear _delay's parameters as we call it's execute() next
	181	+ _delay.execute(cli); // call _delay's execute() method to print the delay
	182	+ } else {
	183	+ cli.print_P(PSTR("Can't blink slower"));// print an error message if half blink delay is out of bounds
	184	+ }
	185	+ return false; // return false as we're done
	186	+ }
	187	+};
	188	+
	189	+
	190	+// Initialize the Blink Command Line Interface
	191	+const char banner[] PROGMEM = "Blink Sample CLI"; // Banner to show upon startup of the CLI
	192	+CLI CLI(Serial, banner); // Initialize the CLI, telling it to attach to Serial
	193	+Mode_Command Mode(CLI, BLINKING); // Initialize/Register mode command, BLINKING initially
	194	+Delay_Command Delay(CLI); // Initialize/Register delay command
	195	+Faster_Command Faster(CLI, Delay); // Initialize/Register faster command
	196	+Slower_Command Slower(CLI, Delay); // Initialize/Register slower command
	197	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
	198	+
	199	+
	200	+// the setup function runs once when you reset or power the board
	201	+void setup() {
	202	+ // initialize digital pin LED_BUILTIN as an output.
	203	+ pinMode(LED_BUILTIN, OUTPUT);
	204	+
	205	+ // Initialize the Serial port for the CLI
	206	+ while (!Serial); // For Leonardo: wait for serial USB to connect
	207	+ Serial.begin(9600);
	208	+}
	209	+
	210	+// variable to be preserved
	211	+unsigned long last_blink = 0;
	212	+
	213	+// the loop function runs over and over again forever
	214	+void loop() {
	215	+ // First handle CLI, if this returns true, a command is running and the code
	216	+ // block with blink logic is skipped till the command has finished executing
	217	+ if (!CLI.process()) {
	218	+ // check if mode is blinking and last_blink was longer ago than delay
	219	+ // millis() will wrap every 49 days, below approach is wrap-proof
	220	+ if (Mode.get() == BLINKING && millis() - last_blink > Delay.get()) {
	221	+ last_blink = millis(); // led state will change, store when
	222	+ digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // invert LED PIN
	223	+ }
	224	+ }
	225	+}
	226	+
...	...

examples/DS1307RTC/DS1307RTC.ino 0 → 100644

View file @47b5f8d

	1	+++ a/examples/DS1307RTC/DS1307RTC.ino
	1	+/*
	2	+ DS1307RTC.ino - CLI library sample implementing a CLI to control a DS1307 RTC
	3	+
	4	+ Version 1.0, latest version, documentation and bugtracker available at:
	5	+ https://gitlab.lindenaar.net/arduino/CLI
	6	+
	7	+ Copyright (c) 2019 Frederik Lindenaar
	8	+
	9	+ This example shows how to add commands to read and set an DS1307 RTC (Real
	10	+ Time Clock) module to the CLI. It extends the Debug example so that the CLI
	11	+ library debugging commands are also included to check the I2C bus wiring and
	12	+ access the module's NVRAM and EEPROM. The implementation uses Paul
	13	+ Stoffregen's DS1307RTC library (https://github.com/PaulStoffregen/DS1307RTC)
	14	+ so please ensure you have added that (and it's dependency TimeLib) through
	15	+ the Aruino IDE's built-in library manager.
	16	+
	17	+ The following commands are available through the Serial Monitor (available
	18	+ from the Tools menu of the Arduino IDE):
	19	+ - ds1307 Set and/or show DS1307 RTC date and time
	20	+ - eeprom_dump dump the contents of the built-in EEPROM
	21	+ - i2c_scan scan the I2C bus for slave devices
	22	+ - i2c_dump dump the contents of I2C attached EEPROM or Memory
	23	+ - reset restart the microcontroller (software reset)
	24	+ - help show the available commands and how to use them
	25	+
	26	+ To read the the DS1307 use:
	27	+ ds1307 show the current time of the DS1307
	28	+ i2c_dump 0x68 64 8 single show NVRAM (assuming device ID is 0x68)
	29	+ (dump 56-byte NVRAM, start at offset 8)
	30	+
	31	+ To set the DS1307 clock use:
	32	+ ds1307 2019-01-01 12:34:56 to set both the date and time
	33	+ ds1307 2019-01-31 to set only the date
	34	+ ds1307 12:34 to set only the time (seconds set to 0)
	35	+
	36	+ When your module also has an EEPROM (assuming device ID is 0x50) use:
	37	+ i2c_dump 0x50 4096 dump 24LC32 EEPROM contents (4k)
	38	+
	39	+ Please note that the ds1307 command is implemented in separate files (that
	40	+ opens in a separate tab in the Arduino IDE)
	41	+
	42	+ This sketch is free software: you can redistribute it and/or modify it under
	43	+ the terms of version 3 of the GNU General Public License as published by the
	44	+ Free Software Foundation, or (at your option) a later version of the license.
	45	+
	46	+ This code is distributed in the hope that it will be useful but WITHOUT ANY
	47	+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
	48	+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
	49	+
	50	+ You should have received a copy of the GNU General Public License along with
	51	+ this program. If not, visit <http://www.gnu.org/licenses/> to download it.
	52	+*/
	53	+
	54	+#include <CLI.h>
	55	+#include <Wire.h>
	56	+
	57	+#include "DS1307_Command.h"
	58	+
	59	+// Initialize the Debug Command Line Interface
	60	+const char banner[] PROGMEM = "DS1307RTC Sample CLI"; // Banner to show upon startup of the CLI
	61	+CLI CLI(Serial, banner); // Initialize the CLI, telling it to attach to Serial
	62	+DS1307_Command DS1307RTC(CLI); // Initialize/Register ds1307 command
	63	+EEPROM_Dump_Command EEPROM_Dump(CLI); // Initialize/Register (built-in) eeprom_dump command
	64	+I2C_Scan_Command I2C_Scan(CLI); // Initialize/Register (built-in) i2c_scan command
	65	+I2C_Dump_Command I2C_Dump(CLI); // Initialize/Register (built-in) i2c_dump command
	66	+Reset_Command Reset(CLI); // Initialize/Register (built-in) reset command
	67	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
	68	+
	69	+
	70	+// the setup function runs once when you reset or power the board
	71	+void setup() {
	72	+ // initialize digital pin LED_BUILTIN as an output.
	73	+ pinMode(LED_BUILTIN, OUTPUT);
	74	+
	75	+ // Initialize the Serial port for the CLI
	76	+ while (!Serial); // For Leonardo: wait for serial USB to connect
	77	+ Serial.begin(9600);
	78	+
	79	+ // Initialize the Wire Interface
	80	+ Wire.begin();
	81	+
	82	+}
	83	+
	84	+
	85	+// the loop function runs over and over again forever
	86	+void loop() {
	87	+ // handle CLI, if this returns true a command is running. Set Builtin LED accordingly
	88	+ if (CLI.process()) {
	89	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on when processing CLI command
	90	+ } else {
	91	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off when not processing CLI command
	92	+ }
	93	+}
	94	+
...	...

examples/DS1307RTC/DS1307_Command.cpp 0 → 100644

View file @47b5f8d

	1	+++ a/examples/DS1307RTC/DS1307_Command.cpp
	1	+/*
	2	+ DS1307_Command.cpp - CLI library for Arduino/ESP8266 - DS1307 Command implementation
	3	+
	4	+ Version 1.0, latest version, documentation and bugtracker available at:
	5	+ https://gitlab.lindenaar.net/arduino/CLI
	6	+
	7	+ Copyright (c) 2019 Frederik Lindenaar
	8	+
	9	+ This library is free software: you can redistribute it and/or modify it under
	10	+ the terms of version 3 of the GNU General Public License as published by the
	11	+ Free Software Foundation, or (at your option) a later version of the license.
	12	+
	13	+ This code is distributed in the hope that it will be useful but WITHOUT ANY
	14	+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
	15	+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
	16	+
	17	+ You should have received a copy of the GNU General Public License along with
	18	+ this program. If not, visit <http://www.gnu.org/licenses/> to download it.
	19	+*/
	20	+
	21	+#include <TimeLib.h>
	22	+#include <DS1307RTC.h>
	23	+
	24	+#include "DS1307_Command.h"
	25	+
	26	+DS1307_Command::DS1307_Command(CLI &cli) : // Constructor for ds1307 command
	27	+ CLI_Command(cli, // CLI to register with
	28	+ PSTR("ds1307"), // Command name
	29	+ PSTR("Set and/or show DS1307 RTC date and time"), // Description
	30	+ PSTR("Usage:\tds1307 [YYYY-MM-DD] [HH:MM[:SS]]\n" // Usage Help
	31	+ "where YYYY-MM-DD is the date in ISO format\n"
	32	+ " and HH:MM[:SS] the new time (seconds are optional)\n")) { };
	33	+
	34	+// macro to determine whether the given year is a leap year
	35	+#define LEAP_YEAR(y) (!((y) % 4) && (((y) % 100 ) \|\| !((y) % 400) ))
	36	+
	37	+inline uint8_t monthDays(int y, uint8_t m) { // get number of days for month
	38	+ return (m == 2) ? 28 + LEAP_YEAR(y) : 30 + ((m & 1) == (m <= 7));
	39	+}
	40	+
	41	+
	42	+// Function below parses the string passed in params (if provided) and sets the
	43	+// time accordingly. returns false in case an invalid date/time was found (and
	44	+// an invalid parameter message will be given) and true in case of no params or
	45	+// when a string of the format: [YYYY-MM-DD] [HH:MM[:SS]] is found. In case a
	46	+// partial date/time is provided, the remaining part will be substituted with
	47	+// the DS1307's current value. Additional whitespaces are ignored and values are
	48	+// checked for validity.
	49	+bool DS1307_Command::setparams(const char *params) {
	50	+ if (!params) return true; // return true when no parameter
	51	+ int value;
	52	+ tmElements_t tm;
	53	+ if (const char *sep = CLI_STR_parseInt(params, value)) { // parse first integer value
	54	+ RTC.read(tm); // Got a valid start get current time
	55	+ // check if character following the integer is a '-' and we have a valid year
	56	+ if (*sep == '-' && value >= tmYearToCalendar(0) && value <= tmYearToCalendar(255)) {
	57	+ // Got a valid year and date separator, parse the rest of the date
	58	+ tm.Year = CalendarYrToTm(value);
	59	+ if ((sep = CLI_STR_parseInt(sep + 1, value)) && value >= 1 && value <= 12 && *sep == '-') {
	60	+ tm.Month = value;
	61	+ if ((sep = CLI_STR_parseInt(sep + 1, value)) && value >= 1 &&
	62	+ value <= monthDays(tmYearToCalendar(tm.Year), value)) {
	63	+ tm.Day = value;
	64	+ sep = CLI_STR_skipSep(sep);
	65	+ if (*sep) sep = CLI_STR_parseInt(sep, value); // parse the hour integer
	66	+ } else return false; // exit if parsing a date and day is invald
	67	+ } else return false; // exit if parsing a date and month is invald
	68	+ }
	69	+ // check if character following the integer is a ':' and we have a valid hour
	70	+ if (*sep == ':' && value >= 0 && value < 24) {
	71	+ // Got a valid hour and time separator, parse the rest of the time
	72	+ tm.Hour = value;
	73	+ if ((sep = CLI_STR_parseInt(sep + 1, value)) && value >= 0 && value <= 59) {
	74	+ tm.Minute = value;
	75	+ if (*sep == ':') { // if next char is a separator, parse seconds
	76	+ if ((sep = CLI_STR_parseInt(sep + 1, value)) && value >= 0 && value <= 59) {
	77	+ tm.Second = value;
	78	+ } else return false;
	79	+ } else tm.Second = 0; // otherwise set seconds to 0
	80	+ } else return false; // exit if minutes is invalid
	81	+ }
	82	+ if (*CLI_STR_skipSep(sep)) return false; // if not the end of the string, return false
	83	+ RTC.write(tm); // if we get here, we have a valid time in tm, set it
	84	+ return true; // return true as we got valid input
	85	+ }
	86	+ return false; // no valid parameter, return false
	87	+}
	88	+
	89	+bool DS1307_Command::execute(CLI &cli) { // execute prints the current time
	90	+ tmElements_t tm;
	91	+ if (RTC.read(tm)) { // get current time from DS1307
	92	+ cli.print(dayStr(tm.Wday)); // print day of week
	93	+ cli.print(' ');
	94	+ cli.print(tm.Day); // print day of month
	95	+ cli.print(' ');
	96	+ cli.print(monthStr(tm.Month)); // print month name
	97	+ cli.print(' ');
	98	+ cli.print(tmYearToCalendar(tm.Year)); // print year
	99	+ cli.print(' ');
	100	+ cli.print2digits(tm.Hour); // print hour
	101	+ cli.print(':');
	102	+ cli.print2digits(tm.Minute); // print minute
	103	+ cli.print(':');
	104	+ cli.print2digits(tm.Second); // print seconds
	105	+ } else { // if get time fails, print an error
	106	+ if (RTC.chipPresent()) { // if a chip was found, it is not set
	107	+ cli.print_P(PSTR("Error: cannot read RTC clock, please set time\n"));
	108	+ } else { // otherwise tell user no DS1307 was found
	109	+ cli.print_P(PSTR("Error: RTC clock not found, check wiring\n"));
	110	+ }
	111	+ }
	112	+ return false; // We're done and should not be called again
	113	+}
	114	+
...	...

examples/DS1307RTC/DS1307_Command.h 0 → 100644

View file @47b5f8d

	1	+++ a/examples/DS1307RTC/DS1307_Command.h
	1	+/*
	2	+ DS1307_Command.cpp - CLI library for Arduino/ESP8266 - DS1307 Command definitions
	3	+
	4	+ Version 1.0, latest version, documentation and bugtracker available at:
	5	+ https://gitlab.lindenaar.net/arduino/CLI
	6	+
	7	+ Copyright (c) 2019 Frederik Lindenaar
	8	+
	9	+ This library is free software: you can redistribute it and/or modify it under
	10	+ the terms of version 3 of the GNU General Public License as published by the
	11	+ Free Software Foundation, or (at your option) a later version of the license.
	12	+
	13	+ This code is distributed in the hope that it will be useful but WITHOUT ANY
	14	+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
	15	+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
	16	+
	17	+ You should have received a copy of the GNU General Public License along with
	18	+ this program. If not, visit <http://www.gnu.org/licenses/> to download it.
	19	+*/
	20	+
	21	+#include <CLI.h>
	22	+
	23	+class DS1307_Command : public CLI_Command { // Definition of ds1307 command
	24	+ public:
	25	+ DS1307_Command(CLI &cli); // Constructor, requires CLI
	26	+ bool setparams(const char *params); // Parameter parser
	27	+ bool execute(CLI &cli); // Implementation of logic
	28	+};
	29	+
...	...

examples/Debug/Debug.ino 0 → 100644

View file @47b5f8d

	1	+++ a/examples/Debug/Debug.ino
	1	+/*
	2	+ Debug.ino - CLI library sample implementing a CLI for the Blink sample code
	3	+
	4	+ Version 1.0, latest version, documentation and bugtracker available at:
	5	+ https://gitlab.lindenaar.net/arduino/CLI
	6	+
	7	+ Copyright (c) 2019 Frederik Lindenaar
	8	+
	9	+ This sketch demonstrates the debugging commands available as part of the CLI
	10	+ library. These commands are intended to eliminate the need to write code to
	11	+ check things in or connected to your microcontroller. Over time, additional
	12	+ commands will be added, when needed (feel free to submit your favorites for
	13	+ inclusion!). At this moment it makes the following commands available through
	14	+ the Serial Monitor (available from the Tools menu of the Arduino IDE):
	15	+ - eeprom_dump dump the contents of the built-in EEPROM
	16	+ - i2c_scan scan the I2C bus for slave devices
	17	+ - i2c_dump dump the contents of I2C attached EEPROM or Memory
	18	+ - reset restart the microcontroller (software reset)
	19	+ - help show the available commands and how to use them
	20	+
	21	+ For each of these commands the implementation is included in the CLI library.
	22	+
	23	+ This sketch is free software: you can redistribute it and/or modify it under
	24	+ the terms of version 3 of the GNU General Public License as published by the
	25	+ Free Software Foundation, or (at your option) a later version of the license.
	26	+
	27	+ This code is distributed in the hope that it will be useful but WITHOUT ANY
	28	+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
	29	+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
	30	+
	31	+ You should have received a copy of the GNU General Public License along with
	32	+ this program. If not, visit <http://www.gnu.org/licenses/> to download it.
	33	+*/
	34	+
	35	+#include <CLI.h>
	36	+#include <Wire.h>
	37	+
	38	+// Initialize the Debug Command Line Interface
	39	+const char banner[] PROGMEM = "Debug Sample CLI"; // Banner to show upon startup of the CLI
	40	+CLI CLI(Serial, banner); // Initialize the CLI, telling it to attach to Serial
	41	+EEPROM_Dump_Command EEPROM_Dump(CLI); // Initialize/Register (built-in) eeprom_dump command
	42	+I2C_Scan_Command I2C_Scan(CLI); // Initialize/Register (built-in) i2c_scan command
	43	+I2C_Dump_Command I2C_Dump(CLI); // Initialize/Register (built-in) i2c_dump command
	44	+Reset_Command Reset(CLI); // Initialize/Register (built-in) reset command
	45	+Help_Command Help(CLI); // Initialize/Register (built-in) help command
	46	+
	47	+
	48	+// the setup function runs once when you reset or power the board
	49	+void setup() {
	50	+ // initialize digital pin LED_BUILTIN as an output.
	51	+ pinMode(LED_BUILTIN, OUTPUT);
	52	+
	53	+ // Initialize the Serial port for the CLI
	54	+ while (!Serial); // For Leonardo: wait for serial USB to connect
	55	+ Serial.begin(9600);
	56	+
	57	+ // Initialize the Wire Interface
	58	+ Wire.begin();
	59	+}
	60	+
	61	+
	62	+// the loop function runs over and over again forever
	63	+void loop() {
	64	+ // handle CLI, if this returns true a command is running. Set Builtin LED accordingly
	65	+ if (CLI.process()) {
	66	+ digitalWrite(LED_BUILTIN, HIGH); // turn LED on when processing CLI command
	67	+ } else {
	68	+ digitalWrite(LED_BUILTIN, LOW); // turn LED off when not processing CLI command
	69	+ }
	70	+}
	71	+
...	...

keywords.txt 0 → 100644

View file @47b5f8d

	1	+++ a/keywords.txt
	1	+#######################################
	2	+# Syntax Coloring Map for CLI v1.0
	3	+#######################################
	4	+
	5	+#######################################
	6	+# Datatypes (KEYWORD1)
	7	+#######################################
	8	+CLI KEYWORD1
	9	+CLI_Command KEYWORD1
	10	+
	11	+CLI_State KEYWORD1
	12	+CLI_Command_Param KEYWORD1
	13	+CLI_Command_Flags KEYWORD1
	14	+
	15	+Help_Command KEYWORD1
	16	+Reset_Command KEYWORD1
	17	+EEPROM_Dump_Command KEYWORD1
	18	+I2C_Scan_Command KEYWORD1
	19	+I2C_Dump_Command KEYWORD1
	20	+
	21	+#######################################
	22	+# Methods and Functions (KEYWORD2)
	23	+#######################################
	24	+
	25	+# functions
	26	+CLI_STR_skipSep KEYWORD2
	27	+CLI_STR_findSep KEYWORD2
	28	+CLI_STR_parseInt KEYWORD2
	29	+CLI_STR_parseParam_P KEYWORD2
	30	+CLI_STR_parseFlags_P KEYWORD2
	31	+
	32	+# CLI
	33	+process KEYWORD2
	34	+add_command KEYWORD2
	35	+get_command KEYWORD2
	36	+find_command KEYWORD2
	37	+command_count KEYWORD2
	38	+print_P KEYWORD2
	39	+print2digits KEYWORD2
	40	+print_mem KEYWORD2
	41	+printtab KEYWORD2
	42	+
	43	+# CLI_Command
	44	+matches KEYWORD2
	45	+setparams KEYWORD2
	46	+execute KEYWORD2
	47	+
	48	+#######################################
	49	+# Constants (LITERAL1)
	50	+#######################################
	51	+CLI_MAX_CMDS LITERAL1
	52	+CLI_MAX_LINE LITERAL1
	53	+
	54	+STATE_INIT LITERAL1
	55	+STATE_READY LITERAL1
	56	+STATE_INPUT LITERAL1
	57	+STATE_PARSE LITERAL1
	58	+STATE_EXEC LITERAL1
	59	+
...	...

library.json 0 → 100644

View file @47b5f8d

	1	+++ a/library.json
	1	+{
	2	+ "name": "CLI",
	3	+ "description": "Library to buid a real-time serial (or network) command-line interface (CLI) to configure or control your microcontroller.",
	4	+ "keywords": "CLI, Commandline",
	5	+ "homepage": "https://gitlab.lindenaar.net/arduino/CLI",
	6	+ "authors": {
	7	+ "name": "Frederik Lindenaar",
	8	+ "url": "https://frederik.lindenaar.nl",
	9	+ "maintainer": true
	10	+ },
	11	+ "repository": {
	12	+ "type": "git",
	13	+ "url": "https://gitlab.lindenaar.net/arduino/CLI.git"
	14	+ },
	15	+ "version": "1.0",
	16	+ "license": "GPL",
	17	+ "frameworks": [ "arduino" ],
	18	+ "platforms": "*",
	19	+ "examples": "examples//.ino"
	20	+}
	21	+
...	...

library.properties 0 → 100644

View file @47b5f8d

	1	+++ a/library.properties
	1	+name=Command Line Interface
	2	+version=1.0
	3	+author=Frederik Lindenaar
	4	+maintainer=Frederik Lindenaar
	5	+sentence=Library to build a Command Line Interface (CLI)
	6	+paragraph=Library to bui;d a real-time serial (or network) command-line interface (CLI) to configure or control your microcontroller.
	7	+category=Device Control
	8	+url=https://gitlab.lindenaar.net/arduino/CLI
	9	+architectures=*
	10	+license=GPL
	11	+includes=CLI.h
	12	+
...	...

src/CLI.cpp 0 → 100644

View file @47b5f8d

	1	+++ a/src/CLI.cpp
	1	+/*
	2	+ * CLI.cpp - CLI library for Arduino/ESP8266 and others implementation
	3	+ *
	4	+ * Version 1.0, latest version, documentation and bugtracker available at:
	5	+ * https://gitlab.lindenaar.net/arduino/CLI
	6	+ *
	7	+ * Copyright (c) 2019 Frederik Lindenaar
	8	+ *
	9	+ * This library is free software: you can redistribute it and/or modify it under
	10	+ * the terms of version 3 of the GNU General Public License as published by the
	11	+ * Free Software Foundation, or (at your option) a later version of the license.
	12	+ *
	13	+ * This code is distributed in the hope that it will be useful but WITHOUT ANY
	14	+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
	15	+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
	16	+ *
	17	+ * You should have received a copy of the GNU General Public License along with
	18	+ * this program. If not, visit <http://www.gnu.org/licenses/> to download it.
	19	+ */
	20	+
	21	+#include <CLI.h>
	22	+
	23	+#define CHAR_TAB '\t'
	24	+#define CHAR_BS '\b'
	25	+#define CHAR_DELETE char(127)
	26	+#define CHAR_CR '\r'
	27	+#define CHAR_LF '\n'
	28	+
	29	+const char CLI_DEFAULT_PROMPT[] PROGMEM = "\n> ";
	30	+const char CLI_PREFIX_PARAMETER_ERROR[] PROGMEM = "Invalid parameters for ";
	31	+const char CLI_PREFIX_UNKNOWN_COMMAND[] PROGMEM = "Unknown command ";
	32	+
	33	+size_t CLI::print_P (const char *str PROGMEM) {
	34	+ size_t len = 0;
	35	+ if (str) {
	36	+ while (char c = pgm_read_byte(str++)) {
	37	+ write(c);
	38	+ len++;
	39	+ }
	40	+ }
	41	+ return len;
	42	+}
	43	+
	44	+void CLI::print2digits(uint8_t num, char filler, uint8_t base) {
	45	+ if (num < base) print(filler);
	46	+ print(num, base);
	47	+}
	48	+
	49	+void CLI::print_mem(uint16_t addr, const uint8_t buff[], uint8_t len, uint8_t width) {
	50	+ if (addr < 0x1000) print(' ');
	51	+ if (addr < 0x100) print(' ');
	52	+ if (addr < 0x10) print(' ');
	53	+ print(addr, HEX);
	54	+ print(':');
	55	+
	56	+ for (uint8_t i = 0; i < len; i++) {
	57	+ print(' ');
	58	+ if (buff[i] < 0x10) print(0);
	59	+ print(buff[i], HEX);
	60	+ }
	61	+ while (width > len++) print_P(PSTR(" "));
	62	+
	63	+ print('\t');
	64	+ for (uint8_t i = 0; i < len; i++)
	65	+ write(isprint(buff[i]) ? buff[i] : '.');
	66	+
	67	+ println();
	68	+}
	69	+
	70	+void CLI::printtab() {
	71	+ print(CHAR_TAB);
	72	+};
	73	+
	74	+CLI::CLI(Stream &stream, const char banner PROGMEM, const char prompt PROGMEM) : _stream(&stream), _banner(banner) {
	75	+ _state = STATE_INIT;
	76	+ _command_count = 0;
	77	+ _prompt = (prompt) ? prompt : CLI_DEFAULT_PROMPT;
	78	+};
	79	+
	80	+void CLI::add_command(CLI_Command *cmd) {
	81	+ if (_command_count < CLI_MAX_CMDS)
	82	+ _commands[_command_count++] = cmd;
	83	+};
	84	+
	85	+CLI_Command *CLI::get_command(int index) {
	86	+ return (index < _command_count) ? _commands[index] : NULL;
	87	+}
	88	+
	89	+CLI_Command CLI::get_command(const char name, int namelen) {
	90	+ for (int i = 0; i < _command_count; i++) {
	91	+ if (_commands[i]->matches(name, namelen)) return _commands[i];
	92	+ }
	93	+ return NULL;
	94	+}
	95	+
	96	+#if CLI_MAX_CMDS < 255
	97	+uint8_t CLI::find_command(const char *name, int namelen) {
	98	+ uint8_t idx = _command_count;
	99	+#else
	100	+uint16_t CLI::find_command(const char *name, int namelen) {
	101	+ uint16_t idx = _command_count;
	102	+#endif
	103	+ while (idx-- && !_commands[idx]->matches(name, namelen));
	104	+ return idx;
	105	+}
	106	+
	107	+bool CLI::process() { // Workhorse of the CLI
	108	+ if (_state == STATE_INIT) { // INIT: print banner (if set)
	109	+ if (_banner) {
	110	+ print_P(_banner);
	111	+ println();
	112	+ }
	113	+ _state = STATE_READY;
	114	+ } else if (_state == STATE_READY) { // READY: print prompt & init
	115	+ print_P(_prompt);
	116	+ memset(_cmdbuffer, 0, _line_len);
	117	+ _line_len = 0;
	118	+ _current_cmd = NULL;
	119	+ _state = STATE_INPUT;
	120	+ } else if (_state == STATE_INPUT) { // INPUT: process user input
	121	+ while (available()) { // loop while stream input
	122	+ int c = read(); // get next char
	123	+ if (c == CHAR_DELETE) { // Process BACKSPACE key
	124	+ print_P(PSTR("\b \b"));
	125	+ if (_line_len) _cmdbuffer[_line_len--] = 0;
	126	+ } else if (c == CHAR_CR) { // Process ENTER key
	127	+ println();
	128	+ _state = STATE_PARSE; // Change state to PARSE
	129	+ return false; // and stop processing input
	130	+ } else if (c != CHAR_LF && isprint(c)) { // Process other valid input
	131	+ if (_line_len < CLI_MAX_LINE - 1) { // add to line if space left
	132	+ _cmdbuffer[_line_len++] = c;
	133	+ write(c); // print char to echo input
	134	+ } else { // if not, beep & ignore
	135	+ write(char(7));
	136	+ }
	137	+ }
	138	+ }
	139	+ } else if (_state == STATE_PARSE) { // PARSE: parse user command
	140	+ const char *cmd = CLI_STR_skipSep(_cmdbuffer); // skip initial whitespace
	141	+ if (*cmd && cmd - _cmdbuffer < _line_len) { // do we have a command?
	142	+ for (char p = _cmdbuffer + _line_len - 1; p == ' '; p--, _line_len--)
	143	+ *p = 0; // clear trailing whitespace
	144	+ const char *sep = CLI_STR_findSep(cmd); // find end of command
	145	+ if (_current_cmd = get_command(cmd, sep - cmd)) { // known command?
	146	+ sep = CLI_STR_skipSep(sep); // get start of params
	147	+ if (_current_cmd->setparams((*sep) ? sep : 0)) {// parse params
	148	+ _state = STATE_EXEC; // all OK, change state
	149	+ return true; // and stop processing
	150	+ } else print_P(CLI_PREFIX_PARAMETER_ERROR); // print invalid parameters
	151	+ } else print_P(CLI_PREFIX_UNKNOWN_COMMAND) ; // print unknown command
	152	+ _stream->write(cmd, sep - cmd); // print command name
	153	+ println(); // and add newline
	154	+ }
	155	+ _state = STATE_READY; // if we get here: READY
	156	+ } else if (_state == STATE_EXEC) { // EXEC: execute the command
	157	+ if (_current_cmd->execute(*this)) { // Execute, false when done
	158	+ return true; // not yet done, return true
	159	+ } else {
	160	+ _state = STATE_READY; // done, READY
	161	+ }
	162	+ }
	163	+ return false; // default result false (done)
	164	+}
	165	+
	166	+
	167	+CLI_Command::CLI_Command(CLI &cli, const char command, const char description, const char *usagehelp) : command(command), description(description), usagehelp(usagehelp) {
	168	+ cli.add_command(this);
	169	+};
	170	+
	171	+bool CLI_Command::matches(const char *cmd, uint8_t cmdlen) {
	172	+ return pgm_read_byte(&command[cmdlen]) == 0 && strncmp_P(cmd, command, cmdlen) == 0;
	173	+};
	174	+
	175	+bool CLI_Command::setparams(const char *params) {
	176	+ return !params;
	177	+}
	178	+
...	...

src/CLI.h 0 → 100644

View file @47b5f8d

	1	+++ a/src/CLI.h
	1	+/*
	2	+ * CLI.h - CLI library for Arduino/ESP8266 and others definitions
	3	+ *
	4	+ * Version 1.0, latest version, documentation and bugtracker available at:
	5	+ * https://gitlab.lindenaar.net/arduino/CLI
	6	+ *
	7	+ * Copyright (c) 2019 Frederik Lindenaar
	8	+ *
	9	+ * This library is free software: you can redistribute it and/or modify it under
	10	+ * the terms of version 3 of the GNU General Public License as published by the
	11	+ * Free Software Foundation, or (at your option) a later version of the license.
	12	+ *
	13	+ * This code is distributed in the hope that it will be useful but WITHOUT ANY
	14	+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
	15	+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
	16	+ *
	17	+ * You should have received a copy of the GNU General Public License along with
	18	+ * this program. If not, visit <http://www.gnu.org/licenses/> to download it.
	19	+ */
	20	+
	21	+#include <Stream.h>
	22	+
	23	+#ifndef CLI_H
	24	+#define CLI_H
	25	+
	26	+#ifndef CLI_MAX_CMDS
	27	+ #define CLI_MAX_CMDS 16
	28	+#endif // CLI_MAX_CMDS
	29	+
	30	+#ifndef CLI_MAX_LINE
	31	+ #define CLI_MAX_LINE 80
	32	+#endif // CLI_MAX_LINE
	33	+
	34	+class CLI;
	35	+
	36	+struct CLI_Command_Param {
	37	+ const char *param PROGMEM;
	38	+ union {
	39	+ int int16;
	40	+ uint16_t uint16;
	41	+ int8_t int8;
	42	+ uint8_t uint8;
	43	+ int32_t int32;
	44	+ uint32_t uint32;
	45	+ char *str PROGMEM;
	46	+ };
	47	+};
	48	+
	49	+struct CLI_Command_Flags {
	50	+ const char *command;
	51	+ uint8_t cmdlen, flags, intparam;
	52	+};
	53	+
	54	+const char CLI_STR_skipSep(const char str);
	55	+const char CLI_STR_findSep(const char str);
	56	+const char CLI_STR_parseInt(const char , int &, int = -32768, int = 32767);
	57	+const char CLI_STR_parse_HEX_byte(const char , uint8_t &);
	58	+const struct CLI_Command_Param CLI_STR_parseParam_P (const char , const struct CLI_Command_Param params[]);
	59	+const char CLI_STR_parseFlags_P (const char , const struct CLI_Command_Flags params[], uint8_t, uint8_t, uint8_t *);
	60	+
	61	+class CLI_Command {
	62	+ friend class Help_Command;
	63	+ friend class CLI;
	64	+ protected:
	65	+ const char command, description, *usagehelp;
	66	+ bool matches(const char *cmd, uint8_t cmdlen);
	67	+ public:
	68	+ CLI_Command(CLI &cli , const char command PROGMEM, const char description PROGMEM, const char *help PROGMEM = NULL);
	69	+ virtual bool setparams(const char *params);
	70	+ virtual bool execute(CLI &cli) = 0;
	71	+};
	72	+
	73	+
	74	+class Help_Command : public CLI_Command {
	75	+ CLI &_cli;
	76	+#if CLI_MAX_CMDS < 255
	77	+ uint8_t _cmd_idx;
	78	+#else
	79	+ uint16_t _cmd_idx;
	80	+#endif
	81	+ bool _cmd_list;
	82	+ public:
	83	+ Help_Command(CLI &cli);
	84	+ bool setparams(const char *);
	85	+ bool execute(CLI &cli);
	86	+};
	87	+
	88	+
	89	+class EEPROM_Dump_Command : public CLI_Command {
	90	+ int _offset;
	91	+ public:
	92	+ EEPROM_Dump_Command(CLI &cli);
	93	+ bool setparams(const char *);
	94	+ bool execute(CLI &cli);
	95	+};
	96	+
	97	+class Reset_Command : public CLI_Command {
	98	+ int _resetting;
	99	+ public:
	100	+ Reset_Command(CLI &cli);
	101	+ bool execute(CLI &cli);
	102	+};
	103	+
	104	+class I2C_Scan_Command : public CLI_Command {
	105	+ uint8_t _address, _found;
	106	+ public:
	107	+ I2C_Scan_Command(CLI &cli);
	108	+ bool setparams(const char *);
	109	+ bool execute(CLI &cli);
	110	+};
	111	+
	112	+class I2C_Dump_Command : public CLI_Command {
	113	+ uint8_t _address;
	114	+ bool _large;
	115	+ uint16_t _length, _offset;
	116	+ public:
	117	+ I2C_Dump_Command(CLI &cli);
	118	+ bool setparams(const char *);
	119	+ bool execute(CLI &cli);
	120	+};
	121	+
	122	+
	123	+class CLI : public Stream {
	124	+ enum CLI_State { STATE_INIT, STATE_READY, STATE_INPUT, STATE_PARSE, STATE_EXEC } _state;
	125	+#if CLI_MAX_CMDS < 255
	126	+ uint8_t _command_count;
	127	+#else
	128	+ uint16_t _command_count;
	129	+#endif
	130	+ CLI_Command *_commands[CLI_MAX_CMDS];
	131	+#if CLI_MAX_LINE < 255
	132	+ uint8_t _line_len;
	133	+#else
	134	+ uint16_t _line_len;
	135	+#endif
	136	+ char _cmdbuffer[CLI_MAX_LINE];
	137	+ // const char *_params;
	138	+ CLI_Command *_current_cmd;
	139	+ protected:
	140	+ Stream *_stream;
	141	+ const char _banner, _prompt;
	142	+ public:
	143	+ CLI(Stream &stream, const char banner PROGMEM = NULL, const char prompt PROGMEM = NULL);
	144	+ void add_command(CLI_Command *cmd);
	145	+ CLI_Command *get_command(int);
	146	+ CLI_Command get_command(const char , int);
	147	+#if CLI_MAX_CMDS < 256
	148	+ uint8_t find_command(const char *, int);
	149	+ inline uint8_t command_count() {
	150	+#else
	151	+ uint16_t find_command(const char *, int);
	152	+ inline uint16_t command_count() {
	153	+#endif
	154	+ return _command_count;
	155	+ };
	156	+
	157	+ inline int available() {
	158	+ return _stream->available();
	159	+ };
	160	+
	161	+ inline int peek() {
	162	+ return _stream->peek();
	163	+ };
	164	+
	165	+ inline int read() {
	166	+ return _stream->read();
	167	+ };
	168	+
	169	+ inline size_t write(uint8_t c) {
	170	+ return _stream->write(c);
	171	+ };
	172	+
	173	+ size_t print_P (const char *str PROGMEM);
	174	+ void print2digits(uint8_t num, char filler = '0', uint8_t base=10);
	175	+ void print_mem(uint16_t addr, const uint8_t buff[], uint8_t len, uint8_t width=16);
	176	+ void printtab();
	177	+
	178	+ bool process();
	179	+};
	180	+
	181	+#endif // CLI_H
	182	+
...	...

src/CLI_Utils.cpp 0 → 100644

View file @47b5f8d

	1	+++ a/src/CLI_Utils.cpp
	1	+/*
	2	+ * CLI_Utils.cpp - CLI library for Arduino/ESP8266 and others utility functions
	3	+ *
	4	+ * Version 1.0, latest version, documentation and bugtracker available at:
	5	+ * https://gitlab.lindenaar.net/arduino/CLI
	6	+ *
	7	+ * Copyright (c) 2019 Frederik Lindenaar
	8	+ *
	9	+ * This library is free software: you can redistribute it and/or modify it under
	10	+ * the terms of version 3 of the GNU General Public License as published by the
	11	+ * Free Software Foundation, or (at your option) a later version of the license.
	12	+ *
	13	+ * This code is distributed in the hope that it will be useful but WITHOUT ANY
	14	+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
	15	+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
	16	+ *
	17	+ * You should have received a copy of the GNU General Public License along with
	18	+ * this program. If not, visit <http://www.gnu.org/licenses/> to download it.
	19	+ */
	20	+
	21	+#include <CLI.h>
	22	+
	23	+const char CLI_STR_skipSep(const char str) {
	24	+ while (*str == ' ') str++;
	25	+ return str;
	26	+};
	27	+
	28	+const char CLI_STR_findSep(const char str) {
	29	+ while (str && str != ' ') str++;
	30	+ return str;
	31	+};
	32	+
	33	+const char CLI_STR_parseInt(const char str, int &value, int minvalue, int maxvalue) {
	34	+ int v = 0;
	35	+ const char *p = str;
	36	+ bool negative = *p == '-';
	37	+ if (negative \|\| *p == '+') p++;
	38	+ while (p >= '0' && p <= '9') {
	39	+ v *= 10;
	40	+ v += *(p++) - '0';
	41	+ }
	42	+ if (str != p && v >= minvalue && v <= maxvalue) {
	43	+ value = (negative) ? -v : v;
	44	+ return p;
	45	+ }
	46	+ return 0;
	47	+}
	48	+
	49	+uint8_t parseHexNibble(char c) {
	50	+ if(c >= 'a' && c <= 'f') {
	51	+ return c - 'a' + 10;
	52	+ } else if(c >= 'A' && c <= 'F') {
	53	+ return c - 'A' + 10;
	54	+ } else if(c >= '0' && c <= '9') {
	55	+ return c - '0';
	56	+ } else return 0xff;
	57	+}
	58	+
	59	+const char CLI_STR_parse_HEX_byte(const char str, uint8_t &value) {
	60	+ if (str) {
	61	+ uint8_t v;
	62	+ if((v = parseHexNibble(*(str++))) <= 0xf) {
	63	+ value = v << 4;
	64	+ if((v = parseHexNibble(*(str++))) <= 0xf) {
	65	+ value \|= v;
	66	+ return str;
	67	+ }
	68	+ }
	69	+ }
	70	+ return NULL;
	71	+}
	72	+
	73	+const struct CLI_Command_Param CLI_STR_parseParam_P (const char param, const struct CLI_Command_Param params[]) {
	74	+ for (const struct CLI_Command_Param *p = params; pgm_read_ptr(&p->param); p++)
	75	+ if (!strcmp_P(param, (char *)pgm_read_ptr(&p->param))) return p;
	76	+ return NULL;
	77	+}
	78	+
	79	+const char CLI_STR_parseFlags_P (const char str, const struct CLI_Command_Flags params[], uint8_t param_count, uint8_t mask, uint8_t *flags) {
	80	+ uint8_t f = 0;
	81	+ while (*str) {
	82	+ const struct CLI_Command_Flags *p = params;
	83	+ while (p <= &params[param_count] && strncmp_P(str, pgm_read_word(&p->command), pgm_read_byte(&p->cmdlen)) ) p++;
	84	+ uint8_t flags = pgm_read_byte(&p->flags);
	85	+ if (p > &params[param_count] \|\| (f != 0 && ((f & mask) != (flags & mask)))) return 0;
	86	+ f \|= flags;
	87	+ str = CLI_STR_skipSep(str + pgm_read_byte(&p->cmdlen));
	88	+
	89	+ if (uint8_t intparam = pgm_read_byte(&p->intparam)) {
	90	+ int i;
	91	+ if (str = CLI_STR_parseInt(str, i)) {
	92	+ if (pgm_read_byte(&p->cmdlen) == 0)
	93	+ if (int divider = pgm_read_word(&p->command)) {
	94	+ i /= divider & 0xff;
	95	+ i += divider >> 8;
	96	+ }
	97	+ if (i <= (intparam & 0x1f)) {
	98	+ f \|= i << (intparam >> 5);
	99	+ str = CLI_STR_skipSep(str);
	100	+ continue;
	101	+ }
	102	+ }
	103	+ return 0;
	104	+ }
	105	+ }
	106	+ if (*str) return 0;
	107	+ *flags = f;
	108	+ return str;
	109	+}
	110	+
...	...

src/Commands.cpp 0 → 100644

View file @47b5f8d

	1	+++ a/src/Commands.cpp
	1	+/*
	2	+ * CLI_Commands.cpp - CLI library for Arduino/ESP8266 and others general commands
	3	+ *
	4	+ * Version 1.0, latest version, documentation and bugtracker available at:
	5	+ * https://gitlab.lindenaar.net/arduino/CLI
	6	+ *
	7	+ * Copyright (c) 2019 Frederik Lindenaar
	8	+ *
	9	+ * This library is free software: you can redistribute it and/or modify it under
	10	+ * the terms of version 3 of the GNU General Public License as published by the
	11	+ * Free Software Foundation, or (at your option) a later version of the license.
	12	+ *
	13	+ * This code is distributed in the hope that it will be useful but WITHOUT ANY
	14	+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
	15	+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
	16	+ *
	17	+ * You should have received a copy of the GNU General Public License along with
	18	+ * this program. If not, visit <http://www.gnu.org/licenses/> to download it.
	19	+ */
	20	+
	21	+#include <CLI.h>
	22	+#include <avr/eeprom.h>
	23	+
	24	+Help_Command::Help_Command(CLI & cli) :
	25	+ CLI_Command(cli, PSTR("help"), PSTR("Display command help"),
	26	+ PSTR("Usage: help [<command>]\n"
	27	+ "\tdisplays usage help for <command> or lists available commands\n"
	28	+ "\twhen called without parameters\n")), _cli(cli) { };
	29	+
	30	+bool Help_Command::setparams(const char *params) {
	31	+ if (_cmd_list = !params) {
	32	+ _cmd_idx = 0;
	33	+ return true;
	34	+ } else {
	35	+ _cmd_idx = _cli.find_command(params, strlen(params));
	36	+ return _cmd_idx < _cli.command_count();
	37	+ }
	38	+}
	39	+
	40	+bool Help_Command::execute(CLI &cli) {
	41	+ if(CLI_Command *cmd = cli.get_command(_cmd_idx)) {
	42	+ if (_cmd_list) {
	43	+ if (_cmd_idx == 0) cli.print_P(PSTR("Known Commands:\n"));
	44	+ _cmd_idx++;
	45	+ cli.printtab();
	46	+ if (cli.print_P(cmd->command) < 8) cli.printtab();
	47	+ cli.printtab();
	48	+ cli.print_P(cmd->description);
	49	+ cli.println();
	50	+ return true;
	51	+ } else {
	52	+ cli.print_P(cmd->description);
	53	+ cli.println();
	54	+ if (cmd->usagehelp) cli.print_P(cmd->usagehelp);
	55	+ }
	56	+ } else if (_cmd_list) {
	57	+ cli.print_P((_cmd_idx)
	58	+ ? PSTR("\nfor more information on a command use \"help <command>\"")
	59	+ : PSTR("No Commands"));
	60	+ }
	61	+ cli.println();
	62	+ return false;
	63	+}
	64	+
	65	+
	66	+EEPROM_Dump_Command::EEPROM_Dump_Command(CLI & cli) : CLI_Command(cli,
	67	+ PSTR("eeprom_dump"), PSTR("Show EEPROM contents in HEX and ASCII")) { };
	68	+
	69	+bool EEPROM_Dump_Command::setparams(const char *params) {
	70	+ _offset = 0;
	71	+ return !params && E2END > 0;
	72	+}
	73	+
	74	+bool EEPROM_Dump_Command::execute(CLI &cli) {
	75	+ if (_offset == 0) {
	76	+ cli.print_P(PSTR("EEPROM Size: "));
	77	+ cli.print(E2END + 1);
	78	+ cli.print_P(PSTR(" Bytes\n\n"));
	79	+ }
	80	+ uint8_t buffer[16];
	81	+ eeprom_read_block(&buffer, (void *)_offset, sizeof(buffer));
	82	+ cli.print_mem(_offset, buffer, sizeof(buffer));
	83	+ _offset += sizeof(buffer);
	84	+ return _offset <= E2END;
	85	+}
	86	+
	87	+
	88	+Reset_Command::Reset_Command(CLI & cli) : CLI_Command(cli,
	89	+ PSTR("reset"), PSTR("Restart microcontroller")) { };
	90	+
	91	+void(* resetFunc) (void) = 0; //declare reset function @ address 0
	92	+bool Reset_Command::execute(CLI &cli) {
	93	+ if (_resetting == 2000) resetFunc();
	94	+ if (!_resetting) cli.print(PSTR("resetting...\n\n"));
	95	+ _resetting++;
	96	+ return true;
	97	+}
	98	+
...	...

src/I2C_Commands.cpp 0 → 100644

View file @47b5f8d

	1	+++ a/src/I2C_Commands.cpp
	1	+/*
	2	+ * CLI_I2C_Commands.cpp - CLI library for Arduino/ESP8266 - I2C Commands implementation
	3	+ *
	4	+ * Version 1.0, latest version, documentation and bugtracker available at:
	5	+ * https://gitlab.lindenaar.net/arduino/CLI
	6	+ *
	7	+ * Copyright (c) 2019 Frederik Lindenaar
	8	+ *
	9	+ * This library is free software: you can redistribute it and/or modify it under
	10	+ * the terms of version 3 of the GNU General Public License as published by the
	11	+ * Free Software Foundation, or (at your option) a later version of the license.
	12	+ *
	13	+ * This code is distributed in the hope that it will be useful but WITHOUT ANY
	14	+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
	15	+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
	16	+ *
	17	+ * You should have received a copy of the GNU General Public License along with
	18	+ * this program. If not, visit <http://www.gnu.org/licenses/> to download it.
	19	+ */
	20	+
	21	+#include <CLI.h>
	22	+#include <Wire.h>
	23	+
	24	+I2C_Scan_Command::I2C_Scan_Command(CLI & cli) : CLI_Command(cli,
	25	+ PSTR("i2c_scan"), PSTR("Scan I2C bus for slave devices")) { };
	26	+
	27	+bool I2C_Scan_Command::setparams(const char *params) {
	28	+ _address = _found = 0;
	29	+ return !params;
	30	+}
	31	+
	32	+bool I2C_Scan_Command::execute(CLI &cli) {
	33	+ if (_address < 127) {
	34	+ if (_address == 0) cli.println(F("Scanning I2C..."));
	35	+ Wire.beginTransmission(_address);
	36	+ uint8_t error = Wire.endTransmission();
	37	+
	38	+ if (error == 0) {
	39	+ cli.print(F("I2C device found at address 0x"));
	40	+ if (_address < 0x10) cli.print("0");
	41	+ cli.println(_address, HEX);
	42	+ _found++;
	43	+ } else if (error == 4) {
	44	+ cli.print(F("Unknown error at address 0x"));
	45	+ if (_address < 0x10) cli.print("0");
	46	+ cli.println(_address, HEX);
	47	+ }
	48	+ _address++;
	49	+ return true;
	50	+ } else {
	51	+ if (_found == 0)
	52	+ cli.print_P(PSTR("No I2C devices found"));
	53	+ return false;
	54	+ }
	55	+}
	56	+
	57	+
	58	+I2C_Dump_Command::I2C_Dump_Command(CLI & cli) : CLI_Command(cli,
	59	+ PSTR("i2c_dump"), PSTR("Display I2C EEPROM/Memory in HEX and ASCII"),
	60	+ PSTR("Usage: i2c_dump 0x<id> <size> [<skip>] [single]\n"
	61	+ "where:\t<id>\tHEX I2C device ID\n"
	62	+ "\t<size>\tsize of memory\n"
	63	+ "\t<skip>\t(optional) start offset\n"
	64	+ "\tsingle\tto enforce 1-byte addressing")) { };
	65	+
	66	+bool I2C_Dump_Command::setparams(const char *params) {
	67	+ if (params && (params++) == '0' && (params++) == 'x') {
	68	+ if ((params = CLI_STR_parse_HEX_byte(params, _address)) && *params == ' ') {
	69	+ if(params = CLI_STR_parseInt(CLI_STR_skipSep(params), (int &)_length)) {
	70	+ _offset = 0;
	71	+ _large = _length > 0xff;
	72	+ if (*params == ' ') {
	73	+ params = CLI_STR_skipSep(params);
	74	+ if(const char *p = CLI_STR_parseInt(params, (int &)_offset))
	75	+ params = CLI_STR_skipSep(p);
	76	+ if (strcmp_P(params, PSTR("single")) == 0) {
	77	+ if (_large) return false;
	78	+ params += 6;
	79	+ }
	80	+ }
	81	+ return *params == 0;
	82	+ }
	83	+ }
	84	+ }
	85	+ return false;
	86	+}
	87	+
	88	+bool I2C_Dump_Command::execute(CLI &cli) {
	89	+ uint8_t buffer[16], len = 0;
	90	+
	91	+ Wire.beginTransmission(_address);
	92	+ if (_large) Wire.write((uint8_t)(_offset >> 8)); // MSB
	93	+ Wire.write((uint8_t)(_offset & 0xff)); // LSB
	94	+ if (Wire.endTransmission() != 0) {
	95	+ cli.print(F("No I2C device at 0x"));
	96	+ cli.print(_address, HEX);
	97	+ cli.println();
	98	+ return false;
	99	+ }
	100	+
	101	+ if (_offset == 0) cli.println(F("I2C EEPROM/Memory: "));
	102	+
	103	+ Wire.requestFrom(_address, (uint8_t) (_length - _offset < sizeof(buffer)) ? _length - _offset : sizeof(buffer));
	104	+ while (Wire.available() && len < sizeof(buffer)) buffer[len++] = Wire.read();
	105	+
	106	+ cli.print_mem(_offset, buffer, len);
	107	+ _offset += len;
	108	+ return _offset < _length;
	109	+}
	110	+
...	...